Using the SIMCA®-online web API for developers (Q907)
Summary:
The SIMCA®-online web api provides data from a SIMCA®-online server to clients that connect using http or https. One such client is the SIMCA®-online Web Client described in simca-online-web-client-161.
This article describes what the web api can be used for and how to get started.
The target audience of this article is web software developers. To be able to use the web api effectively you also need experience in using SIMCA®-online so that you know the terminology.
More Information:
High-level overview of the web api functionality
The web api is a RESTful api, that uses http requests and responses to transfer data. Learn more at https://en.wikipedia.org/wiki/Representational_state_transfer. Clients using the web api don't have to be web browsers, but can be any application that can use http.
To be able to use the web api, a client first authenticates against the SIMCA®-online server with SIMCA®-online or Active Directory credentials (if it has been set up on the SIMCA®-online server).
The SIMCA®-online server rules for access rights and permissions apply through the web api as in the desktop client; if a user cannot see a project configuration in the desktop client, they cannot access it through the web api either.
Currently the web api is mostly for reading data for project configurations on the SIMCA®-online server. There is very limited functionality for writing data or changing things on the SIMCA®-online server. One exception is resetting alarms for which there is an api.
The web api will be continuously improved in future SIMCA®-online versions. Learn more about different versions below.
Note: the SIMCA®-online desktop client does not use the api. It connects using Windows remote procedure calls.
The web api is a feature of the SIMCA®-online server
The web api is a feature of the SIMCA®-online server. To use it the Web Server feature must be enabled in the application SIMCA®-online Server Options on the server computer. Learn more in the built-in help in SIMCA®-online.
To test the web api, no SIMCA®-online server license is needed. A SIMCA®-online demo installation can be used.
Since the web api uses http or https on a specific tcp port, any firewalls between the server computer and clients must be configured to allow that traffic through. For production, we recommend using https since it protects the network traffic including usernames and passwords.
As with desktop clients, many connected web api clients can affect performance of the SIMCA®-online server. An app that uses the web api inefficiently can cause unnecessary load on the server.
Developing software using the web api
The remainder of this article is targeted at developers and describes how to develop software using the web api.
Basic SIMCA®-online terminology
To be able to use the web api effectively you have to know about SIMCA®-online. You should spend time using the desktop client and the web client to learn about the product and what can be done.
You have to know what project configurations are and the various settings you can make in SIMCA®-online for project configuration. You also need to know about multivariate modelling such as models, scores, DModX, contributions, variables. SIMCA®-online alarms and notes are available through the web api. The batch functionality of SIMCA®-online is inherently more complicated than the support for continuous project configurations.
Authentication using the /api/v1/login endpoint
Before any other web api calls be used, the client first has to authenticate to the server. Authentication is one using the same credentials as in SIMCA®-online.
The endpoint used for authentication is /api/v1/login.
Form-based authentication (https://en.wikipedia.org/wiki/HTTP%2BHTML_form-based_authentication), json authentication (introduced in SIMCA®-online 15.0.1), or basic authentication (introduced in 16.1) can be used.
For json authentication the server expects a request with content-type 'application/json', with a single stringified json object { "username": "exampleuser", "password": "topsecret" }
After the server verifies the log in, it sends a cookie to the client. The client should then send the same cookie to the server for each subsequent call.
To see how to do this programmatically, you can look in the source code of the web api test bed, which is described next.
Using the test bed to test the Web API
The SIMCA®-online server provides a built-in test bed for the web api. It is available as soon as the Web Server feature is enabled (see above).
To access the web api test bed, navigate to http://servercomputername:9001/test/index.html. In the form that is displayed, log in as a SIMCA®-online user of the server.
The test bed is a simple web page with various buttons and form fields.
- Each button maps a specific web api end point (function).
- The parameters for each endpoint are provided using the form fields.
- Clicking a button calls the server, and returns the result as JSON displayed at the end of the page.
- Some endpoints have a ?-button. Clicking that explains the parameters for that endpoint.
Here is how to get started:
- Click the GetAllItems button to see all project configurations on the server, in a similar way as the Project Administration dialog does in the desktop client.
- To the right of each project configuration, there is a [Test]-link which you click to get to the testbed that specific configuration.
- The testbed for the project configuration has a new set of buttons, each mapping to an endpoint that can be used to obtain data for that project configuration. Note that the buttons displayed are the same regardless if the project is a batch project or a continuous project although for example the batch functionality has no meaning for a continuous project.
Then for example;
- Click GetProjectInfo and you will be presented with data that describes this project configuration.
- Click GetBatches (for a batch project) to see any batches that lived between the times provided (defaults to the latest 24 hours).
- Click GetModelInfo (and provide a model number, such as 1) to get information about model 1
Using browser developer tools to monitor Web Client traffic
Another good way to learn about all the parameters for the web api calls, is to run the SIMCA®-online 15 Web Client in a browser, and use the browser debugging tools to look at the network traffic between the Web Client and the SIMCA®-online server. The browser will show all parameters for all web api calls.
Using Postman
Postman is another tool that you can use to test making web api calls. https://www.getpostman.com/
Further examples
To see the batches that were active during a time range, use the following API:
/api/v1/configurations/configurationId/batches
Arguments: fromTime, toTime. Where fromTime and toTime are permitted to be equal.
The following example will return all batches that were active in configuration b2053824-7b71-48fd-a7b2-0e199fd590aa at 2015-12-11 14:12:00 UTC:
/api/v1/configurations/b2053824-7b71-48fd-a7b2-0e199fd590aa/batches?fromTime=2015-12-11T14:12:00Z&toTime=2015-12-11T14:12:00Z
To get hold of the active phases in a batch, use the following API:
/api/v1/configurations/configurationId/batches/batchId
The following example will return detailed information about all the phases in batch 42 in configuration b2053824-7b71-48fd-a7b2-0e199fd590aa:
/api/v1/configurations/b2053824-7b71-48fd-a7b2-0e199fd590aa/batches/42
To get hold of T2Range for a phase:
/api/v1/configurations/b2053824-7b71-48fd-a7b2-0e199fd590aa/data?batchId=42&modelNumber=1&fromTime=2015-12-11T14:11:00Z&toTime=2015-12-11T14:12:00Z&dataTypes={"comp":{"from":1,"to":3},"type":"T2Range"}
A note about timestamps and time zones
Many endpoints take timestamps as arguments. These timestamps should be in ISO 8601 format in either the server's local time or in UTC format. For example:
- 2021-06-15 14:08 is a local time of the server computer.
- 2021-06-15T12:08Z is a UTC time.
In this particular example, both times refer to the same point in time because the server's time zone is located in UTC+2.
Many endpoints return timestamps in two formats; a string UTC time ending with Z and a Unix timestamp. For example, here is part of the returned JSON:
"startTime": {
"iso": "2021-06-14T13:12:36Z",
"unix": 1623676356
}
Different versions of the API
The SIMCA®-online web API was introduced in SIMCA®-online 14.0, and then updated with new functionality in 15.0, 15.1, 16.0, and now most recently in 16.1. These changes are backwards compatible, meaning that a program developed for the 14 web api will work in the later versions.
This article describes this most recent 16.1 version which is the version we recommend since it is most mature.
Support for developing using the web API
Limited support for developers using the web api are provided from the SIMCA®-online development team. https://umetrics.com/support
As noted above, to be able to use the web api effectively you need not only web development skills, but also SIMCA®-online experience in your team.
