CIMPLICITY REST interfaces provide capabilities to access CIMPLICITY remotely through web interface(https), which allows us to build client applications on any OS, or browser based client applications using the hypermedia provided by CIMPLICITY.
We provide following capabilities are supported from REST API:
Configuration capabilities:
- Points
- Objects
- Users
- Roles
- SQL connections
- Historian connections
Runtime capabilities:
- Start/Stop project
Security and Authentication
From CIMPLICITY 2023 onwards, the following types of authentication methods are supported for REST APIs:
- Basic Authentication
- Bearer Token Authentication
Basic Authentication
You can use basic authentication when CIMPLICITY is used as an identity provider. With this authentication method, you can use native user/domain user credentials to authenticate REST APIs.
Project API: All REST APIs where project is specified are referred as project APIs. You need to acquire sessionId to use these APIs.
Acquiring a session:
To get the session id we need to use following REST API:
URL: POST /cim-config/v1/projects/<PROJECTID>/session
Example URL: https://SAMPLENODE:9443/cim-config/v1/projects/CIMPUACLIENT/session
Where,
SAMPLENODE is the hostname of the machine where the CIMPLICITY server runs.
CIMPUACLIENT is the project ID
Headers:
Authentication: basic auth. (use credentials of any user in the project)
Response: JSON object
{
"inactivityTimeout": 1200000,
"privileges": -1,
"refreshInterval": 900000,
"sessionId": "LCXVttwj5hWX7T/bQpIEbROAq+ZjhUnJtx8oo1zsRaZp8NgN7KPCJCbRHKGVetgIYKt+SBua4uGsmFFlILs0tV0b5nNggPlzI9Nev5UyFKZ5ZwKoGiOS7YQbltOrBR3H/CZhtAeL7ZEQCQIndPbWcWEJVgiRnD57YKh/bITQRQ4wVpN+A8DLgTmtGpJk8b7Bj4FWY6RwtdskNNBLUAKgrgPSuQk58fwrxyfyiOCRorLVYZgbCETyQXit27z3xb7kEedcOa3TGLMz+i5ohob7AnqDHBq/tAWjzwuTHGLGRRZMKnqDJyqaQEYodGpUUF0N"
}
SessionId received is valid for 15 minutes by default.
All project APIs use basic authentication with sessionId as payload.
Example: If we want to create a point using /cim-config/v1/projects/<PROJECTID>/points, we need to add an authorization header as follows.
Basic LCXVttwj5hWX7T/bQpIEbROAq+ZjhUnJtx8oo1zsRaZp8NgN7KPCJCbRHKGVetgIYKt+SBua4uGsmFFlILs0tV0b5nNggPlzI9Nev5UyFKZ5ZwKoGiOS7YQbltOrBR3H/CZhtAeL7ZEQCQIndPbWcWEJVgiRnD57YKh/bITQRQ4wVpN+A8DLgTmtGpJk8b7Bj4FWY6RwtdskNNBLUAKgrgPSuQk58fwrxyfyiOCRorLVYZgbCETyQXit27z3xb7kEedcOa3TGLMz+i5ohob7AnqDHBq/tAWjzwuTHGLGRRZMKnqDJyqaQEYodGpUUF0N
Refresh a session:
As the sessionId is valid only for 15 minutes, we need to refresh token before it expires using refreshsession API
url: /cim-config/v1/projects/<PROJECTID>/refeshsession
Headers:
Authentication: Use basic authentication with sessionId as a payload (same as the project API authentication).
Bearer Token Authentication
You can use bearer token authentication when Proficy Authentication Server is used as an identity provider. To use this authentication method, you must configure Proficy Authentication server and enable Proficy Authentication for the project. For more information on Proficy Authentication, refer to the Proficy Authentication section in the CIMPLICITY online documentation. With this authentication method, you can use Proficy user credentials to authenticate REST APIs.
You can either get token directly from REST APIs provided by Proficy Autnetication or use any utilities like Curl to get the token. See the below examples on genrating token using Curl:
cURL command format for generating an oauth token for clients:
curl -u <client ID>:<client secret> https://<node name>:8443/uaa/oauth/token -d 'grant_type=client_credentials'
Example:
curl -u server1.admin:adminsecret https://server1:8443/uaa/oauth/token -d 'grant_type=client_credentials'
cURL command format for generating an oauth token for UAA users:
curl -d "client_id=<value>&client_secret=<value>&grant_type=password&username=<value>&password=<value>&token_format=opaque&response_type=token" https://<node name>:8080/uaa/oauth/token
Example:
curl -d "client_id=server1.admin&client_secret=adminsecret&grant_type=password&username=user1&password=pwd123&token_format=opaque&response_type=token"
Computer APIs:
Following APIs are computer APIs and use basic authentication. These APIs can be used to work with multiple projects on a computer.
URL: POST /cim-config/v1/user-config
URL: POST /cim-config/v1/rest-settings
Example URL: https://SAMPLENODE:9443/cim-config/v1/user-config
NOTE: The URL does not require a project ID
Where,
SAMPLENODE is the hostname of the machine where the CIMPLICITY server runs.
We need to create a computer user for working with above APIs. We can create a computer user with command line utility RegisterComputerUser.exe, by default we do not create a computer user. Computer user credentials can be used to fill details in Basic Authentication Header.
REST APIs:
Following APIs are supported: