Make your first API call
In this tutorial you sign in to the Profinity Representational State Transfer (REST) API from a command line, and use the token it returns to read the latest value of a tag. At the end you have a token and a JSON response that holds the tag's current value.
What you need
- A running Profinity instance on the same computer, which answers at
http://localhost:18080. The API runs whenever Profinity runs. - The user name and password of a Profinity user with the View tags permission.
- The full path of a tag that currently has a value, such as
Pump/DBC/MotorStatus/Temperature. TAG EXPLORER shows each tag's path and current value. curl, which macOS, Linux, and Windows include, and on Windows, PowerShell.
The tutorial uses localhost, so the password does not cross the network.
An application on another computer needs HTTPS.
Refer to Authenticate to the Profinity REST API for what a client on the network needs.
Get a token
Keep passwords out of scripts
Do not put a real password in a script, in shell history, or in a file under version control. For an application that runs unattended, use a service account, whose token has no expiry.
-
Run the command for your operating system. Replace
<username>and<password>with the user's sign-in details.Run this command in PowerShell:
Invoke-RestMethod -Method Post -Uri http://localhost:18080/api/v2/Users/Authenticate -ContentType "application/json" -Body '{"username": "<username>", "password": "<password>"}'PowerShell shows the response as a list of fields rather than as JSON, with the same field names.
-
Find the
tokenfield in the response. The response looks like this, with thepermissionslist shortened: -
Copy the value of
token. In the JSON response, copy only the text between the quotation marks.
If the response holds a token, you have signed in.
Call an endpoint with the token
-
Run the command for your operating system. Replace
<token>with the token you copied, and<tag-path>with the full path of your tag. -
Check the response. It is a JSON object like this, with your tag's values:
fullTagId is the path you asked for, utcTimestamp is when the sample was taken, and value is the reading.
quality is Good when the value is current, and Stale when the value is older than Profinity allows for a current value.
If the response shows your tag's value, the call worked.
| What you see | Cause | What to do |
|---|---|---|
404 |
The path does not match a tag, the tag has no Good or Stale value at the moment, or the user cannot see the tag. | Copy the path from TAG EXPLORER, check that the tag shows a value there, and check that the user can see its component. |
401 |
The token is missing, mistyped, or has expired. | Get a new token, as in Get a token. For the other causes, refer to Fix 401 and 403 responses. |
403 |
The user does not have the View tags permission. | Give the user a role that holds View tags. |
Next steps
- Read a window of past values with Read real-time and historical tag data.
- Open the Swagger page, which lists every endpoint and its parameters, by adding
/swaggerto the Profinity address. Apply your token there with Authorize, and refer to Use Swagger with a token for the steps. - Look up an API in the API reference.