API Documentation

ID Management Service
Service for creating, updating and managing links between identifiers.
Last updated: 2026-03-30
See revision history

Quickstart to the API

The ID Manager stores links between URIs with metadata, allows you to query and filter the set of links, and manages a unique number system.

Authentication token

To access the API calls that allow you to write and change data within the system, you first need to autheticate to it to get a (JWT) token. Fundamentally, you will authenticate with a username and password, and the service will respond with a token that should be used in all future requests:

POST /auth

JSON data

{
    "username": "...",
    "password": "..."
}

The response will be a JSON object, with an access_token key. The value for that should be included as an HTTP authorization header in future requests. If say the access_token was "TOKEN", then the HTTP header will be:

Authorization: Bearer TOKEN

If you are going to add links, you will need to know five bits of information at the least:

  • The motivation - the reason or purpose or cause of the link. This will be represented by a URI. If it is a very specific purpose, then you may wish to add a motivation to represent it. It is a compromise; The more specific a motivation, the easier it is to manage and find these specific links. If the motivation is a more general purpose one, a more broad range of links (including links you have not added) would be returned from a query using it, which can be useful or not.
  • the body - this will be the URI for one of the resources being linked, along with its 'generator' (the URI representing the system or organization managing its URI)
  • the target - the URI and generator of the other resource being linked. The motivation should infer which one is the body and which should be the target, but if in doubt, the body contains the information leading to the link, and the target is the thing being linked to. (ie a description (body) of a museum piece (target), a paper (body) citing another (target) and so on.)

If this is structured as a link as follows, it can be added to the service:

{
    "motivation": "https://... (motivation URI)",
    "body": {
        "id": "URI TO BODY",
        "generator": "https://... (generator URI for the body)"
    },
    "target": {
        "id": "URI TO TARGET",
        "generator": "https://... (generator URI for the target)"
    }
}

Using HTTP POST, this JSON data can be sent to the /links/ endpoint, and will create the link providing the following is true:

  • the motivation and generator URIs are registered in the system, and
  • this exact combination of five things is not already in the system.

More detail can be found in the API description for Creating links in the Links API documentation

Motivations and Generators

What motivations and Generators are registered can be retrieved from an HTTP GET request to /motivations/ and /generators respectively. These reply with a list of each one registered in the system, and the full uri value should be used when creating or querying the service.

More information about the API for Motivations and Generators

The easiest way to explore what is in the service is through the web interface. Open it in a browser and you will be redirected to the query links screen. Click the blue button to reveal the full query form. If you have the URI of a thing you would like to find links for, paste it into the 'Either body or target' field and click Submit. This will return all the links that the URI features in as either the body or the target of the link. This can be a very useful way to see crosswalks between representations in other systems and services.

query interface