Introduction to Entuity RESTful API

Introduction

OPTIONS method

Multi-server resources

Versioning

Authentication

Introduction

The Entuity RESTful API allows third-party programs to interact with Entuity. It enables you to programmatically integrate and automate processes in the Entuity UI.

The RESTful API is exposed via URLs under the /api path. For example, you can access the information resource through:

• http://entuity_server/api/info
• https://entuity_server/api/info

Each resource may support one or more of the following HTTP methods: GET, POST, PUT, DELETE, OPTIONS. Each resource may require input and may produce output.

Resources can expect input in different forms:

• Query parameters, e.g. https://myserver/api/someResource?param=value. Note that ‘value’ in the example URL must be URL encoded (e.g. ‘hello world’ must be encoded as ‘hello%20world’). For the list of characters that must be encoded, see: https://www.w3schools.com/tags/ref_urlencode.asp.
• HTTP content (Entity). The Entity may be represented as either XML (content-type:application/xml) or JSON (content-type:application/json). Note that when sending entity in the request, you must specify the “content-type” header. If using the curl tool you can use the –H argument to specify the header, e.g. curl –H "content-type:application/json"

Most, but not all, resources will return resource representations in either XML or JSON. You can specify which representation by supplying a ‘media’ query parameter with a value of ‘xml’ or ‘json’, e.g. https://myserver/api/info?media=xml.  Alternatively, you can specify this using a header field, e.g. Accept: application/xml or Accept: application/json.

Each response has a response code, indicating a success/failure of the request. These are standard HTTP specification response codes:

• 200-299: indicates success.
• 300-399: indicates redirection: clients should repeat request at redirected location.
• 400-499: indicates a problem with a client request.
• 500-599: indicates a problem on a server side.

For a full list of Entuity RESTful API resources, please see the Contents article.

• If you are using ENA v18.0 and below, please see Entuity RESTful API v4.8.
• If you are using Entuity v19.0 to Entuity v20.0, please see Entuity RESTful API v4.17.

OPTIONS method

You can get some simple information on a resource’s supported methods by issuing an OPTIONS method against that resource, or you can find all available resources by issuing an OPTIONS method against a root resource. For example, by using curl:

• curl –X OPTIONS https://myserver/api/. This will return an ALLOW header containing the supported methods.

Multi-server resources

By default, HTTP methods operate on the resources local to the server you are speaking to. However, if the server you are speaking to has remote servers configured, you can work with any of them. You can qualify the server you want to be working with by using a query parameter ‘serverId’, e.g. https://mycentralserver/api/info?serverId=long-id-of-the-remote-server.

Versioning

All resources accessible via /api/* can also be accessed via /api/v2/*. Clients who wish to remain compatible with future versions of Entuity should use resources under the specific version: /api/v2/*. Resources without a version specifier under /api/* will contain the latest resource implementations, and may be changed in future releases.

Please note that resources under the specific version /api/v2/* may still be changed with new Entuity versions/patches. However, any changes will be limited to compatible changes that are unlikely to break any integrations making use of the API.

Compatible changes include:

• addition of new authentication methods.
• addition of new resources.
• addition of new fields in resource representations returned.
• requiring fewer inputs.
• applying fewer constraints on input.

Incompatible change will be added with a new version number, so the following URLs will be available:

• /api/v1/* will use version 1 of the API.
• /api/v2/* will use version 2 of the API which will include changes that are not compatible with previous versions.
• /api/* Will always track the latest version of the API.

Resources in this document are described using URLs relative to their version base, e.g. resource 'info' can be accessed as /api/info or /api/v2/info.

Please see the Version history article to check the latest version of the API.

Authentication

Entuity supports basic HTTP authentication method (RFC 2617). Basic HTTP authentication is widely supported. Please note that basic HTTP authentication is insecure when used without SSL, because passwords are sent as clear text). Therefore, Entuity recommends using the API over HTTPS.

If using the curl tool, you can supply '-u username:password' arguments to provide authentication details.

For performance reasons, authentication results are cached on the server for 5 minutes after they are last used.

Note that you can authenticate with any Entuity user and the resources are protected by using the Entuity permission model: Users will only be able to access and modify resources that they have permission to access.

Access key authentication:

Alongside authenticating with a username and password by using the HTTP 'Authorization' header and 'Basic' scheme, you can authenticate with an access key.

The access key can be supplied in the HTTP request's ENA-Api-Key header. Note, if both the 'Authorization' header and the 'ENA-API-Key' are specified, the 'Authorization' header will take precedence and the access key is ignored.

Valid access keys are configured in <ENTUITY_HOME>/etc/accessKeys.properties file. Note, this file does not exist by default, and needs to be created by the administrator. You will need to stop the Entuity server, configure this file, and then restart the Entuity server for the file to work.

The format of the file is as follows:

• single-line comments begin with a hash # symbol.
• access keys are specified in the following format: <access_key> = <ena_username>, where:
  • <access_key> should be a long string which is hard to guess, and should contain the following characters only: 
    • digits (0-9)
    • lower case ASCII characters (a-z)
    • upper case ASCII characters (A-Z)
  • <ena_username> is the name of the existing Entuity account. HTTP requests which authenticate with the provided access key will be performed on behalf of this user.

Example accessKeys.properties:

  # This is a comment

  verystrongsecret = admin

  anotherstrongsecret = user

For authentication with the access key to be successful, the 'ENA-Api-Key' header in the HTTP request must match one of the access keys specified in the file (case sensitive), and the user associated with the access key must already exit in Entuity.