API Documentation

API - Short IDs and Slugs

GET /new-slug/ (PRIV)

A call to this endpoint returns a Crockford Base32, 6-character identifier that is intended to be unique to the environment where the ID manager is deployed. Only the Getty production environment is guaranteed to be unique, although the staging environment will be unique in most cases. The identifier increments in sequence, not randomly. The slug generator uses the integer value of the BASE32_OFFSET environment variable to determine where the encoded identifier sequence starts.

Blueprint "/slugs/"

This is the slug endpoint, allowing for the slug URIs to be resolved to an Annotation response detailing what Link they represent, as well as a conveninence method for getting-or-creating a slug linked to an identifier (with generator). The first call to this method will mint a new slug ID and create a slug Link to the requested id and generator. Subsequent requests to this method with the same id and generator will result in the same slug annotation response.

GET /slugs/{slug_id}

The Annotation response will encode the slug id as a URI (as required by the anno-ld spec), which resolves to this route. The last part of the URI is the system unique base32 slug id. The Annotation response links the slug URI to an identifier and generator. See below for an example Annotation type response.

If a link with this slug id cannot be found, the service will respond with an HTTP 404 error.

POST /slugs/ (PRIV)

POST a JSON body to /slugs/ containing an 'id' and valid 'generator' property to get-or-create a link between it and a slug number minted by the IDM.

copyPOST /slugs/   (with Authorization header)
content: {"id": "my_identifier", "generator": "https://data.getty.edu/local/thesaurus/generators/lodlvl2"}

Response HTTP 201

copy{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "body": {
    "generator": "https://data.getty.edu/local/thesaurus/generators/lodlvl2",
    "id": "my_identifier"
  },
  "created": "2020-07-14T18:01:28Z",
  "id": "https://services.getty.edu/id-management/links/4e7a346a-1772-4854-9cd4-df1fc0b1f92c",
  "modified": "2020-07-14T18:01:28Z",
  "motivation": "https://data.getty.edu/local/thesaurus/motivations/has-slug",
  "target": {
    "generator": "https://data.getty.edu/local/thesaurus/generators/idmanager",
    "id": "https://services.getty.edu/id-management/slugs/100002"
  },
  "type": "Annotation"
}

Optional features of the /slugs/ POST request endpoint are as follows:

• If a valid group_id is provided, it will be added to the slug link record that is created, or updated in the slug link record that was previously created, for the same combination of id and generator values. This feature allows allows the slug link to later be retrieved via the group_id and allows link records generated by the /slugs/ endpoint to be grouped with group_id values in the same way as that link records generated by the /links/ endpoint can be. This feature is particularly useful for being able to retrieve, and in cases of cleanup being able to delete all of the links associated with a given group_id.

If a valid slug_uri_prefix (not None or "") is provided within the JSON-serialized POST request body, it will be used as the URI prefix for the newly minted slug instead of the default slug URI prefix which is sourced from ID Manager's EXTERNAL_HOST_URL environment variable followed by the /slugs/ path component. This feature allows slugs to be generated for specific use-cases and stored in ID Manager in the form they will be used within the wider collections information ecosystem.