The TierPoint API is designed to allow customers and partners the ability to interface with TierPoint programmatically, through a modern, standards-based REST API. The API is designed to provide secure access to key information and resources at TierPoint. The following are some key concepts that should be understood to efficiently use the TierPoint API.
OAuth2 specifies the use of an Authentication token that must be created to access the API endpoints. This is provided via the TierPoint OAuth service
When using any other service, the token must be presented in the HTTP header of the request in the format:
Authorization: Bearer eyJraWQiOiJyc2...
These tokens are JWT compatible, but everything needed to use the token effectively is returned in the oauth service response, including expiration timestamp, and token lifetime (in seconds).
Navigating to the Base URL of the API Site will provide links to the documentation for each TierPoint REST service available. These documentation pages are built in Swagger, and provide essential information required to use the APIs effectively. An example swagger page can be seen in the figure below.
Sample Swagger Page
A key feature is the ‘Try it Out’ button, that allows a user to run the service in their web browser, as if it were being executed elsewhere. For most services, an Authorization token must be entered to use this feature. To do so, click the ‘Authorize’ button, and enter the ‘Bearer <token>’ information in the value box, and click Authorize. See the Figures below for an example:
Authorize Button in Swagger Page
Using OAuth2 Token with Swagger
The TierPoint API is designed to allow developers the ability to interface with our systems consistently while allowing deployment of new features and functionality. Care is taken to minimize impact to developers when releasing new features. However, if a developer-impacting change is made to the API, TierPoint will release a new version of the API, and may continue to support both versions for a time to allow transition to the new version.
The TierPoint API is a JSON-first REST API. As such, it is expected that customer developers are going to use the API using modern data binding techniques. For this reason, not every update to the TierPoint API will merit a version change.
The following are not considered versioning events:
The following are considered versioning events:
API versions are specified in the URL (e.g. v1) when accessing the TierPoint API. There are also some static version labels that will always be available to users, as shown in the table below:
| Version Identifier | Notes |
| v1 | API Version 1 |
| v2 | API Version 2. All versions will be deployed with integer labels. |
| latest | Current API Version. This label will always work, but may break functionality as new versions are deployed. |
| beta | Preview API Version. This label will refer to pre-release versions of the API to test unreleased functionality. These API interfaces are not fixed and may change at any time before final release. This label may not be available to all users in all environments. |
The TierPoint API, per REST standards is designed around synchronous request/response interactions. Some operations, however take longer than is practical for a request/response model. In those cases, the initial request is performed via REST, and a notification is sent in response when the operation is complete. Receipt of this notification is optional, and made available to developers to enhance the usage of the API, but use is not mandatory.
These notifications are also useful when the integrating partner needs to be notified of actions that other users or systems are performing that change the state of data the system is interested in. This limits the use of unnecessary polling to check for these changes.
The TierPoint API uses STOMP over WebSockets to provide this notification channel for partner and customer developers. This provides the following advantages:
A reference implementation has been built to recieve messages. You can download it here.