Rest API - Introduction

SAI360 (EHS&S) features a REST API that uses OData Protocol (http://www.odata.org) for Create, Read and Update operations against records in the SAI360 system, which allows other applications to interact with SAI360.

Getting Started

• Enable Rest API EndPoint in Admin Global Settings System
• Identify the components that need to be available via the Rest API calls for the given business requirement and flag them by following these instructions.
  It is strongly recommended that only the components required to meet specific integration requirements are exposed through the Rest API.
• Rest API call capabilities will be defined via an associated SAI360 User account.
  Create a user (Admin Security Users) and assign the relevant security roles to that user.
  For example, if the Rest API is used for creating Person records, the User needs to have Create, Read and Write security roles to Person and to Department and/or Location if they require to be linked.
• Generate an API Key for the user(s) by following these instructions.
  The API Key is used to authenticate and authorise on all API calls, and the system will enforce the security defined for User account associated with the API Key.
  This lets designers have fine-grain control over what operations are available to any given API Key.

Supported OData Operations

Database CRU operations map to OData operations as follows:

API Schema (Metadata)

The REST API is an OData API. OData APIs are self-describing, which means they expose metadata (all available entity sets, singletons, relationships, entity types, and operations) through the API itself.

An OData metadata document is a representation of the data model that describes the data and operations exposed by the API, and can be retrieved by appending $metadata to the base API URL.

e.g. http://<WebApp_URL>/restapi/component/$metadata

There is no hard-copy API schema documentation, due to the fact that the API is self-describing, but also due to the fact the schema is dynamic and can change moment-to-moment due to configuration changes.

Considerations

As the CRU operations are being performed on Component rather than Form level, clients need to be aware of the following:

• Creating or modifying records via the Rest API will bypass any Form Validations which may exist.

  Validations will only be performed the next time a record is being edited by a user through the web application.

• Any form-based Actions (like changing a Status, or sending an Email) cannot be triggered by executing the Rest API.
• Analytic Rules will be triggered (if configured) on Create and Update.
• The Rest API will adhere to the Component Security and Policy settings, identical to the web application.

  Where there are attribute/field level restrictions configured, the system will respect the security and return the value as "null" - indicating that the user has no read permissions.

  Similarly, the Rest API call will return an exception if the user does not have write permissions to that attribute/level. or write permissions.

  Also, these fields cannot be used for any filtering operations.

• Create, Read and Update operations will be logged in the Audit log.

Updating and Testing Security Settings

When developing Rest API calls, testing of Security settings will be a part of it.

Some API testing tools (for example Postman) cache user settings, with the result that security settings for an API user (e.g. adding or removing Roles for a user) may not be reflected for an extended period of time.

To reduce the turnaround time, our REST API includes a logout call which will force a reload of all security settings on the next call. The process is as follows - assuming that you are already testing Rest API calls for a user in your testing tool:

• In the web application, modify the security setting for a Rest API user.
• Wait for the security reload to happen in SAI360 by checking the log files.
• In your API testing tool, run the following call:
  http://<WebApp-URL>/<WebApp URL>/restapi/component/logout
• Immediately after this, you can test the new settings for your Rest call