Introduction
LCM2M provides live Swagger API documentation at api.lcm2m.com/docs, which allows for interactive experimentation with the API. There are two authorization steps that are required to start interacting with the Swagger documentation.
- Session Request – Send a POST request with your username and password to the /sessions API endpoint to receive a session token.
- Authorization – Use the session token to enable access to the API through the Swagger documentation.
Session Request
Under the JWT Token heading there is a /sessions section that can be expanded by clicking on it. When the section is expanded, a Try it out button will be accessible.
Figure 1 – ‘Try it out’ Button
Clicking the Try it out button will allow you to enter your app.lcm2m.com username and password by replacing the matching string placeholders. If you do not have an LCM2M account, please contact your company admin or LCM2M support to obtain one.
Figure 2 – username and password Entry
Once your login information has been entered, click the Execute button to make the call to the API.
Figure 3 – ‘Execute’ Button
A response should be returned which holds an API token that can be used in the next step. Copy that token (without the quotation marks) to your operating system’s clipboard.
Figure 4 – Token Returned From API
Authorization
At the top of the page, there is an Authorize button with a padlock symbol next to it. Click that and an Available authorizations dialog will appear.
Figure 5 – Authorize Button
Enter the token your received back from the API into the Value field.
Figure 6 – Value Field on Authorization Dialog
After clicking the Authorize button on the dialog, you should see something similar to Figure 7.
Figure 7 – Authorization Complete
You can now click the Close button on that dialog and you will be ready to interact with the API documentation.
Example: Cycle Data
This section gives an example of using the API to pull cycle data from a single piece of equipment.
To begin pulling cycle data, click on the /equipment/{equipId}/cycles section under the Raw Data header.
Figure 8 – Raw Data Section
Clicking on the Try it out button will bring up editable fields for entering the filters for the cycles you want. Two fields are required, and those are equipId (Equipment ID) and startDate (Start Date). The equipment ID can be found by clicking on the piece of equipment you are pulling cycles for in the web UI. The equip ID is the number at the end of the URL for the equipment.
The equipment ID can also be found by using the /equipment endpoint of the API, but that is beyond the scope of this example.
Below is a listing of the parameters that are involved in requesting cycles for a piece of equipment.
The cycles returned by the API after clicking the Execute button will be in the Response body field. A file containing the JSON text representation of this data can be downloaded by clicking the Download button below the response field.
Figure 10 – Download Button for Response Data
The key/value pairs in the returned JSON data require some explanation, and the table below attempts to do so. The data object has a collection of numeric keys that relate to the LCM2M database structure. This object can be ignored as all of the values have counterparts with text IDs.
Example: Status Data
This section gives an example of using the API to pull historical status data for a single piece of equipment.
To begin pulling status data, click on the /equipment/{equipId}/statuslogs section under the Raw Data header.
Figure 11 – Raw Data Status Logs Section
Clicking on the Try it out button will bring up editable fields for entering the filters for the status logs you want. Two fields are required, and those are equipId (Equipment ID) and startDate (Start Date). The equipment ID can be found by clicking on the piece of equipment you are pulling status logs for in the web application at lcm2m.com. The equip ID is the number at the end of the URL for the equipment.
Figure 12 – Equipment ID in URL
The equipment ID can also be found by using the /equipment endpoint of the API, but that is beyond the scope of this example.
Below is a listing of the parameters that can be used when requesting status logs for a piece of equipment.
The status logs returned by the API after clicking the Execute button will be in the Response body field. A file containing the JSON text representation of this data can be downloaded by clicking the Download button below the response field.
Figure 13 – Download Button For Status Log Results
The key/value pairs in the returned JSON data require some explanation, and the table below attempts to do so.
Next Steps
Other forms of data are available through the API, and are listed in the Swagger documentation. If you have a question about the API, or would like to request sample code to help get started with the API, please contact LCM2M support.
CADDIS Systems is protected by U.S. Patent No. 11,675,347.
Copyright © 2023 CADDIS Systems | Accessibility
