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 the 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, append "swagger/UI/index" to the Enterprise site URL, as seen in the example below:
https://MyEnterpriseSite.com/swagger/UI/index
Users can paste their EQuIS API key token into the api_key field in the upper right corner of the Swagger UI frame to allow Swagger to use the token for authentication when using the "Try it out!" button. Users assigned to the REST API role can generate a token in the Security tab of the User Profile Editor in EQuIS Enterprise. Cut and paste the user token into the api_key field and then click the Explore button.
Click on any available resource to display the associated HTTP methods (e.g., GET, PUT). Click on a Method to view details or run a query with the "Try it out!" button.
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). The user must be assigned to the REST API role for any authentication mechanism to succeed. Users assigned to the REST API role can generate an API token in the Security tab of the User Profile Editor in EQuIS Enterprise.