Back to Main Menu

REST API Introduction

A REST endpoint provides way to map a URI and HTTP method simply and directly into the Assetic API framework.

 

Implementing web services with REST has become recognized as a leading method to provide shared services to be consumed by a diverse web clients. 

 

There are a large number of articles and examples around utilising REST endpoints for integration.  The Assetic documentation provides a large number of relevant samples for utilising the Assetic REST API

 
Note: Connections to Assetic are only allowed through HTTPS (TLS 1.2) on port 443. Port 80 is redirected to port 443.
 
Note: There is an API rate limit of 250 requests per minute per user. When the limit is exceeded a 429 error code is returned.

Assetic apidocs Page

You can obtain a complete list of REST endpoints exposed by the Assetic Integration APIs by logging into Assetic Cloud and then appending "/apidocs" to the environment URL shown in the browser address bar  (i.e. https://your_org.assetic.net/apidocs). The APIs are documented in the Open API Specification 2.0 format (formerly known as "Swagger").

 

The screenshot below shows an example of the apidocs page. 

 

Each section can be expanded to reveal the APIs for that section.  In the screenshot below the APIs within the 'Asset' section are shown, and a short description of each API is provided.

 

Each individual API endpoint can then be clicked to expand and display the API schema and parameters. It is possible to also use this page to try out each REST endpoint exposed via the API (click on the highlighted 'Try it out!' button). The 'Example Value' section shows the structure of the endpoint response, and selecting 'Model' will show a list of mandatory and optional inputs.

 

To test the API endpoints using a specific user, or integration account, the username and password fields can be changed at the top of the apidocs page and then select 'Explore'. 

 

The user credentials will then be authenticated and any API requests submitted through the apidocs page will be performed by the specified user.

Assetic API Access Control

Assetic REST APIs require an API password token for authentication. A password token must be generated for every User being utilised for API access.

 

Authentication is Basic Authentication that transmits credentials as user ID/password pairs, encoded using base64 in the Authorization header.

 

Authorisation (i.e. access rights) is then managed via the system permissions of the User.

To retrieve an API password token log into the Assetic system under the desired account and:

  • Open a new browser tab and append "/api/v2/auth/token" to your Assetic site URL i.e. https://your_org.assetic.net/api/v2/auth/token
  • The password token will be generated and displayed in the browser window (circled in the screenshot below)

 
Note:
  • If you want to use a user account with fewer privileges you can do a Proxy Login to retrieve the API password token for another user account. 
  • Each time a token is requested the previous token becomes inactive and the new token must be used to authenticate to the API