SLM API Usage Guide
SLM API usage enables external applications and integration tools to communicate programmatically with Safety Lifecycle Manager. Through the API, authorized requests can retrieve SLM information, navigate object relationships, create or modify objects and create supported process events.
An Application Programming Interface (API) defines methods and data formats that software applications can use to request and exchange information. Within SLM, these endpoints provide an integration layer that allows other applications to interact with SLM data and functionality.
This SLM API usage guide covers accessing the API, authentication, object methods, parent and child relationships, creating and modifying objects, event endpoints and an example of using SLM API data within a C# application.
Getting Started with the Integration
SLM API usage is not restricted to a single development tool or programming language. The training demonstrates API requests using several different approaches, including:
- Postman
- cURL from the Windows command line
- A C# application
- The API documentation provided through an SLM instance
A simple way to test connectivity is the API ping endpoint. The training demonstrates sending a GET request to the ping endpoint and receiving a response from the SLM API.
The same endpoint can be called using a C# application, cURL or Postman, demonstrating that the underlying API can be accessed through different clients capable of making the appropriate HTTP request.
SLM also provides API documentation through the instance, where available endpoints can be reviewed and tested.
For the wider infrastructure in which the API operates, see the SLM On-Premise Hardware and Software Requirements guide.
Authentication and API Keys
Many SLM API operations require authentication. In the examples demonstrated in the training, the SLM API key is passed in the request headers before an authenticated endpoint is executed.
This applies to operations including retrieving protected object information, navigating object relationships, creating objects, updating objects, deleting objects and creating events.
API keys should therefore be treated as security-sensitive credentials. Applications using the API need access to the appropriate key, but that credential should not be unnecessarily exposed through source code, user interfaces, logs or other locations accessible to unauthorized users.
Authentication should be considered at the beginning of an integration rather than added after API functionality has been developed. Requests that require authentication will need the correct SLM API key supplied according to the API requirements demonstrated within the instance documentation.
Retrieving SLM Objects with the API
A major area of SLM API usage is retrieving information about objects. The Objects endpoint allows a request to specify the type of object to retrieve.
For example, the training demonstrates retrieving site information by supplying the appropriate site type ID. The API response returns information for the matching objects together with information such as the total count.
Results can also be filtered when a specific object’s unique identifier is known. Supplying the relevant object identifier allows the request to return information for that particular object rather than the complete set.
This provides the foundation for integrations that need to query selected SLM information programmatically instead of relying on manual navigation through the application.
Navigating Parent and Child Object Relationships
SLM data has relationships between objects, and the API provides endpoints that can be used to navigate those relationships.
The parents endpoint can retrieve parent information for a specific object. The training demonstrates this with a unit, where the returned parent information includes its Enterprise and Site.
The request identifies the object using information including its type and unique hash before requesting the parent relationship. Results can then be filtered to a particular parent type where required.
The children endpoint performs the opposite operation. Given a specific object, it can retrieve information about objects that exist beneath it.
For example, a request can retrieve the children of a unit and then filter those results to a particular object type, such as SIFs.
These endpoints make parent and child navigation particularly useful when an external application needs to understand the context of an SLM object rather than retrieve it as an isolated record.
Creating Objects with SLM API Usage
SLM API usage can also extend beyond retrieving data. The training demonstrates creating a new SLM object using a POST request to the Objects endpoint.
The creation payload contains information including:
- The type ID of the object being created
- The parent relationship for the new object
- The data fields required for the object
In the training example, a new unit is created beneath an existing site. The request identifies the site using its unique hash and supplies fields for the new unit including its object ID, unit name, short ID and unit type.
Authentication is required, so the SLM API key is passed in the request header.
After successful creation, the demonstrated endpoint returns an HTTP 201 response together with information about the newly created object and its unique hash. Reloading SLM then shows the unit beneath the specified site.
Updating and Deleting SLM Objects
The API also supports operations for modifying and deleting existing objects.
To update an object, the training uses the PUT Objects endpoint. The request identifies the object using its hash and supplies the fields that need to be modified within the payload.
For example, the training modifies a site’s short ID and address. After the request is executed, the response contains the object data with the updated values, and those changes can subsequently be seen within SLM.
Deleting an object uses the DELETE Objects endpoint. The object to be removed is identified by its hash, and authentication is again supplied through the SLM API key.
Because API operations can change or remove application data, applications using create, update or delete endpoints should ensure that the intended object and payload have been identified correctly before submitting a request.
Creating SLM Events Through API Endpoints
Another important area of SLM API usage is the creation of events. The training demonstrates API endpoints for three event categories:
- Bypass events
- Demand events
- Test events
A bypass activation can be created using the relevant POST event endpoint. The payload identifies the function where the bypass will be established and contains the applicable bypass fields. After execution, the response includes the unique hash and associated information for the newly created bypass.
Demand events use a separate POST endpoint. The request identifies the relevant function and can include device-event failure data for specified devices.
The training demonstrates creating failure information for an input device and an output device. For other online devices where failure information is not supplied in the demand-event payload, a passed device event is created.
Test events are created through the test-record endpoint. The payload identifies the test group and contains the test-event fields together with device-event data that should be recorded with the test.
There is an important distinction between the demonstrated demand and test workflows. For a test event, only supplied device-event data results in device events. For the demonstrated demand event, online devices without supplied failure information receive device events containing passed values.
The SLM Cloud Gateway Interface Guide provides an example of how another SLM component uses the API to send detected plant process events into SLM.
Understanding SLM API Requests and Responses
SLM API usage requires an integration to send the correct HTTP method, endpoint, authentication information and, where required, a request payload.
The transcript demonstrates several common HTTP methods:
- GET for retrieving information
- POST for creating objects and events
- PUT for modifying existing objects
- DELETE for deleting objects
Responses provide information that allows the calling application to determine the result of a request. Examples in the training include HTTP 200 responses for successful operations and an HTTP 201 response following successful object creation.
GET response information demonstrated in the C# example includes:
- Status
- Data
- Total count
- Limit
- Offset
The contents of the data element vary according to the information requested.
For general HTTP semantics, developers can refer to the IETF HTTP Semantics specification, which defines standard HTTP request methods and response status-code behaviour. The SLM instance documentation should remain the source for the specific SLM endpoints, payloads and authentication requirements used by an integration.
Using the SLM API in a C# Application
The training concludes with a C# demonstration showing how SLM API usage can be incorporated into an external application. This example demonstrates practical SLM API usage for retrieving and presenting selected SLM data programmatically.
The demonstration accepts an API URL and API key and then retrieves site information through the Objects endpoint. Returned information is presented in a table containing fields such as site ID, site name and description.
When a site is selected, the application uses children endpoints to retrieve information about function types beneath that site. The example considers function categories including SIF, interlock, alarm and BPCS.
The demonstration uses response models to work with API data. A general response model represents elements including status, data, total count, limit and offset, while additional models extract only the fields needed for the particular application.
The application’s GET method establishes the API client, constructs the request, includes the API key for authentication, performs the call and deserializes the returned information into the required type.
This illustrates an important principle for SLM integrations: an external application does not necessarily need every field returned by an endpoint. It can model and use the information required for its particular workflow.
For example, the demonstration requests a limit of one when calculating function counts because the application is interested in the total count rather than the detailed information for every function returned by the children endpoint.
Through these object, relationship and event endpoints, the SLM API provides a programmatic integration layer for applications that need to retrieve SLM data or perform supported operations without relying exclusively on manual interaction with the SLM interface.
