UI API
The UI API, the UI group in Swagger, returns the schema that dashboards follow and saves a dashboard for the active profile or for one component. A tool that builds dashboards reads the schema, checks its output against it, and then saves the result.
Refer to Authenticate to the Profinity REST API for how to get and pass a token.
A 401 means the request has no valid token.
A 403 means the token's user lacks the permission in the Permission column.
A 403 also comes back from every endpoint on this page while a server installation runs in restricted mode, because its licence is missing or has expired.
The message names the licence state, and Licensing explains how to leave restricted mode.
Each endpoint below lists only its other errors.
| Method | Endpoint | Permission | Purpose |
|---|---|---|---|
| GET | /api/v2/UI/schema |
No permission beyond signing in | Returns the schema for dashboards. |
| PUT | /api/v2/UI |
Modify dashboards | Saves the dashboard of the active profile. |
| PUT | /api/v2/UI/Component/{component} |
Modify dashboards | Saves the dashboard of one component. |
In an endpoint, {component} is the component's name as the side menu shows it, URL encoded, so Pump 1 becomes Pump%201.
Dashboard schema
GET /api/v2/UI/schema
Returns the schema for dashboards. The schema names every element a dashboard can use and the fields of each, so a tool can build a dashboard and check it before it saves. Read it on each run, because the elements an instance offers change with its release. Any signed-in user can read it.
Replace <token> with a token from any signed-in user, and use the address that users type to reach Profinity in place of http://localhost:18080.
The call worked when the response is a JSON document.
This endpoint has no errors of its own beyond sign-in and permission.
Dashboard saves
A save takes the dashboard as JSON, in the same shape as the dashboard YAML that Build a dashboard describes. Convert YAML to JSON before you send it, because a save does not accept YAML. Profinity checks the body against the schema, and a body that fails the check saves nothing.
PUT /api/v2/UI
Saves the dashboard of the active profile.
It needs the Modify dashboards permission, and returns 200 with { "message": "Dashboard successfully saved" }.
Replace these placeholders:
<dashboard-file>with the path of a file that holds the dashboard as JSON, checked against the schema.<token>with a token from a user who has Modify dashboards.
Use the address that users type to reach Profinity in place of http://localhost:18080.
The save worked when the response is { "message": "Dashboard successfully saved" }.
PUT /api/v2/UI returns this error:
| What you see | Cause | What to do |
|---|---|---|
400 |
The body is empty, cannot be parsed, or fails the dashboard schema. | Correct the part the message names, checking it against GET /api/v2/UI/schema. |
PUT /api/v2/UI/Component/{component}
Saves the dashboard of one component.
It writes the file that the component's SETTINGS.DashboardFilename names, and dashboard.yaml when the setting is empty.
Set SETTINGS.DashboardFilename to dashboard.yaml after the first save, with the settings endpoints.
It needs the Modify dashboards permission, and returns 200 with { "message": "Dashboard successfully saved" }.
Replace these placeholders:
<component>with the component's name, URL encoded, such asPump%201.<dashboard-file>with the path of a file that holds the dashboard as JSON, checked against the schema.<token>with a token from a user who has Modify dashboards.
Use the address that users type to reach Profinity in place of http://localhost:18080.
The save worked when the response is { "message": "Dashboard successfully saved" }.
PUT /api/v2/UI/Component/{component} returns these errors:
| What you see | Cause | What to do |
|---|---|---|
400 |
The body is empty, cannot be parsed, or fails the dashboard schema. | Correct the part the message names, checking it against GET /api/v2/UI/schema. |
404 |
No component in the profile has that name. | Add the component first, with the Active profile API. |