The Aristotle Metadata Public REST API¶

The Aristotle Metadata Public REST API enables you to interact with an Aristotle Metadata Registry programmatically. Use this API to build apps, connect other systems to your registry, or develop any other type of integration. This page documents the REST resources available in the Aristotle Metadata Registry.

Description¶

This documentation is for version 4 of the Aristotle Metadata REST API, which is the latest version.

The API is versioned and deprecated slowly so that existing applications have time to transition. Currently version 4 is the only version available.

The Aristotle Metadata REST API’s are available at https:/<your_site>/api/v4 and provide access to content within the system in a machine readable form

Swagger documentation is automatically generated for each api. This describes the endpoints along with expected data and is available at /api/v4

Authentication and authorization¶

Most operations in this API require permissions. To access private content or to perform actions (such as creating, editing or deleting metadata) through the API you need to either be logged in to the site or provide an access token.

Access tokens can be created from the token management page and must be assigned explicit permissions which determined the endpoints each token is able to access.

To use the token it must be provided in the Authenticate http header in the form Token mytoken. For example if your token is Ykc7ClFLUiQKKG8 the Authenticate header should be Token Ykc7ClFLUiQKKG8

Anonymous access¶

Many operations in this API require certain permissions, however many read-only operations can be performed by anonymous users. However, content will only be available to anonymous users if the metadata or content is published for “Public” users.

Pagination¶

The Aristotle Metadata REST API uses pagination to improve performance. Pagination is enforced for operations that can return a large numbers of items. When you request a resource that supports pagination, the response wraps the returned array of values in a JSON object with information on how to access the next and previous pages. For example, to request a list of Workgroups within Aristotle, you would see the following:

{
    "count": 53,
    "next": https://aristotle.example.com/api/v4/workgroups/?page=2,
    "previous": null,
    "results": [
        {
            "id": 4,
            "created": "2020-07-30T22:31:57.929012+10:00",
            "modified": "2020-07-30T22:31:57.929012+10:00",
            "uuid": "a8d2a1a0-d260-11ea-8131-0242ac130008",
            "name": "My team",
            "state": "active",
            "definition": "",
            "stewardship_organisation": "8a1d5d6a-c1d3-11ea-9ece-0242ac130007"
        },
        ...
    ]
}

Status codes¶

The Aristotle Metadata REST API uses standard HTTP status codes <https://en.wikipedia.org/wiki/List_of_HTTP_status_codes>. Requests that return an error status code may also return a response body containing details of the error or errors.