REST (REpresentational State Transfer) is a software pattern and practice built on HTTP (Hyper-Text Transfer Protocol) standards for managing online resources. An Application Programming Interface (API) allows two systems to communicate with one another, with an endpoint being one end of the communication channel. REST does not implement an API. REST describes how HTTP is being used to implement one.
REST focuses on the resources (Files, EDDs, Notices,…) by defining a naming scheme to uniquely identify a resource and its relationship to others through URLs. For example, in the EQuIS data domain, a business entity will have Facilities that have Locations from which Samples were collected and subsequently tested. A REST URL for this may look like:
GET https://onlineauw.equisonline.com/api/facilities/1/locations/949/samples/2345/tests/
EarthSoft has chosen to rely on EUID (EQuIS Unique ID) values rather than codes to identify objects. REST uses HTTP methods (or verbs) to perform actions on the addressed objects. (See https://tools.ietf.org/html/rfc7231 for more information.)
The most commonly used HTTP methods in the EQuIS REST API are:
•GET – Retrieve a representation of a resource.
•POST – Create a new resource to an existing URL (sending data to the server).
•PUT – Create a new resource to a new URL, or modify an existing resource to an existing URL.
•DELETE – Delete an existing resource.
The EQuIS REST API requires a REST API License applied to the EQuIS database (EQuIS Enterprise URL) and the EQuIS users must be assigned the REST API role. All operations require an authenticated user. The EQuIS REST API token must be passed as the Authorization header of the request as follows:
Authorization: Bearer <token>
For example, the header may look like the following (token has been shortened for display purposes):
Authorization: Bearer eyJhtsxeelk...lcK
Resource Organization
The EQuIS REST API is organized along product module lines. API.Core implements the core functionality for EQuIS Enterprise (e.g., Widgets, EDP Workflow, Reporting). API.Collect implements the web services that comprise EQuIS Collect. There are also API.SPM and API.Live.
As of the 7.20.3 Build, the core API includes OData (Open Data Protocol) access to the EQuIS Schema. OData is another pattern and practice based on REST principals. It defines an architectural pattern for direct manipulation of data. This is a departure from previous restrictions on accessing the EQuIS Schema directly. The OData API WILL NOT enforce business rules that are enforced by the remainder of the EQuIS REST API.
Obsolete Methods: There are some endpoints that were direct ports from EQuIS Version 6, which are being phased out in favor of more RESTful equivalents. Most of them are already marked as obsolete while others will soon be marked obsolete. EarthSoft may mark an endpoint obsolete to indicate it should no longer be used but will retain the endpoint for a year allowing third party products time to migrate. We chose this model over the more traditional API versioning approach because it follows EarthSoft’s product development practices.
Swagger
EarthSoft uses Swagger to document our REST API for any EQuIS Installation. Swagger is a specification for documenting REST API. It specifies the format (URL, method, and representation) to describe REST web services. It also provides tools to generate/compute the documentation from application code. (See https://swagger.io/ for detailed information on Swagger.)
A Swagger document is machine readable data formatted in JSON (JavaScript Object Notation), which is available in every installation of EQuIS Enterprise. The Swagger document is dynamic in that it represents the current configuration for an EQuIS installation. EarthSoft provides a Swagger User Interface (UI) to read the Swagger document. The Swagger UI will interpret the Swagger JSON document, allowing users to explore the EQuIS API. The Swagger JSON document can be accessed directly via the link at the top of the Swagger UI page. The Swagger JSON document can also be consumed by other software/services, such as Azure Power Automate.
To access the Swagger UI, a user must authenticate into an Enterprise site and append "swagger/UI/index" to the Enterprise site URL (e.g., https://MyEnterpriseSite.com/swagger/UI/index). The following screen shot shows an example of what a user will see when viewing Swagger.
Users can collapse/expand the endpoint groups and scroll through the available endpoints. Once the desired endpoint is found, click the expand arrow to see the available parameters and responses. Click the Try it now button to interact with the endpoint. In the following example screen shots, a user is interested in seeing information about a facility so they are using the GET /api/facilities/{facilityId} endpoint.
The user entered a facilityId of 1 in the parameter value(s) and will click Execute to run the endpoint.
If configured correctly, the endpoint will run and return a response. In the current example, a successful response was returned which included information for the facility with facilityId equal to 1.
Licensing
Connection to EQuIS using REST API is through an EQuIS 7 Enterprise site, Build 19300 or later. The EQuIS 7 Enterprise site must also have a REST API License applied (see the Enterprise Applying Licenses article). Users assigned to the REST API role can generate an API token in the Security tab of the User Profile Editor in EQuIS Enterprise.