API Documentation

API - Motivation and Generator endpoints

API calls to list, add, delete and update motivation URIs and Generator URIs in the system.

Get list of registered Motivations

A motivation is a concept that defines how and for what reason two URIs are linked. (Specifically, it should correspond to a SKOS concept.) While there is no implied direction of the link in the Web Annotation model, it is common for the body URI to be the source or the reason for the link, and the target URI to be the item or thing that it is linked to. For example, an essay that talks about a museum item, the motivation in the link describing this would commonly have the essay URI to be the body, and the museum item to be the target.

Retrieve the list of registered Motivation URIs. Any attempt to add a link with an unregistered motivation will fail, as these must be added to the system before use. Each motivation added should have a description, especially if it is a bespoke URI.

URL : /motivations

Method : GET

Auth required : NO

Permissions required : None

HTML/JSON : Both

Success Response

Code : 200 OK

Content examples

JSON

The list will contain each motivation in the system, with the full uri being the value that should be used as its ID in requests.

copy{
  "motivations": [
    {
      "description": "dcterms:source to link a target to a body representation that it was sourced or derived from. If the body changes, the target should be updated.",
      "id": 11,
      "uri": "http://purl.org/dc/terms/source"
    },
    {
      "description": "The body object contains a 'RefId' identifier, represented here as the target id",
      "id": 12,
      "uri": "https://data.getty.edu/local/thesaurus/motivations/contains-refid"
    },
    {
      "description": "The body object contains Accession or Acquisition ID, represented here as the target id",
      "id": 13,
      "uri": "https://data.getty.edu/local/thesaurus/motivations/contains-acqno"
    },
    {
      "description": "The body object contains Accession or Acquisition ID and a RefID. The target represents an amalgamation of the two to ensure uniqueness.",
      "id": 14,
      "uri": "https://data.getty.edu/local/thesaurus/motivations/contains-acqno-refid"
    },

    ...


}

Get list of registered Generators

The Generators are specific to the URIs they describe, and will be representative of the systems that control, create and administer the URI in question. This can be an instance of a system, or it can refer to a organization. Often, the link URIs describe resources that do not natively have a URI of their own as the system they are in may not be present on the internet, or may only have an API or DB with its own primary keys. Together, an ID and its generator is used to describe a resource precisely.

Retrieve the list of registered Generator URIs. Any attempt to add a link with an unregistered generator will fail, as these must be added to the system before use. Each generator added should have a description, especially if it is a bespoke URI.

URL : /generators

Method : GET

Auth required : NO

Permissions required : None

HTML/JSON : Both

Success Response

Code : 200 OK

Content examples

JSON

The list will contain each generator in the system, with the full uri being the value that should be used as its ID in requests.

copy{
  "generators": [
    {
      "description": "Getty Museum Collection LOD Gateway",
      "id": 134,
      "uri": "https://data.getty.edu/local/thesaurus/generators/museum-collection-lod-gateway"
    },
    {
      "description": "Gallery Systems' The Museum System (TMS)",
      "id": 6,
      "uri": "https://data.getty.edu/local/thesaurus/generators/tms"
    },
    {
      "description": "OpenText Media Manager (OTMM)",
      "id": 4,
      "uri": "https://data.getty.edu/local/thesaurus/generators/otmm"
    },
    {
      "description": "Getty Union List of Artist Names (ULAN)",
      "id": 166,
      "uri": "https://data.getty.edu/local/thesaurus/generators/ulan"
    },

    ...

}

Register a Motivation

Add a motivation to the registered list

URL : /motivations

Method : POST

Auth required : YES

HTML/JSON : JSON

Data requirements

copy{
  "uri": "MOTIVATION_URI", 
  "description": "Textual description of the purpose of the motivation"
}

Success Response

Code : 201 Created

copy{
  "uri": "MOTIVATION_URI", 
  "description": "Textual description of the purpose of the motivation",
  "id": PRIMARY_KEY_INTEGER
}

Error Responses

Code: 403 - if the user does not have sufficient authorization to add a motivation

Code: 400 Bad Request

copy{
  "errors": [
    {
      "title": "Bad request.",
      "detail": "Check that the request body contains a suitable JSON payload.",
    }
  ]
}

Register a Generator

Add a generator to the registered list

URL : /generators

Method : POST

Auth required : YES

HTML/JSON : JSON

Data requirements

copy{
  "uri": "GENERATOR_URI", 
  "description": "Textual description of the generator"
}

Success Response

Code : 201 Created

copy{
  "uri": "GENERATOR_URI", 
  "description": "Textual description of the generator",
  "id": PRIMARY_KEY_INTEGER
}

Error Responses

Code: 403 - if the user does not have sufficient authorization to add a motivation

Code: 400 Bad Request

copy{
  "errors": [
    {
      "title": "Bad request.",
      "detail": "Check that the request body contains a suitable JSON payload.",
    }
  ]
}

Delete a Motivation

Delete a motivation AND WILL DELETE ALL LINKS USING IT. Important, no undo!

URL : /motivations/MOTIVATION_URI

Method : DELETE

Auth required : YES

HTML/JSON : JSON

Success Response

Code : 200 Okay

copy{"title": "Motivation URI Deleted"}

Error Responses

Code: 403 - if the user does not have sufficient authorization to add a motivation

Code: 400 Bad Request - can also occur if the motivation does not exist

copy{
  "errors": 
    [
      {"title": "Not Found."}
    ]
}

Delete a Generator

Delete a generator AND WILL DELETE ALL LINKS USING IT. Important, no undo!

URL : /generators/GENERATOR_URI

Method : POST

Auth required : YES

HTML/JSON : JSON

Success Response

Code : 200 Okay

copy{"title": "Generator URI Deleted"}

Error Responses

Code: 403 - if the user does not have sufficient authorization to add a motivation

Code: 400 Bad Request

copy{
  "errors": [
    {
      "title": "Bad request.",
      "detail": "Check that the request body contains a suitable JSON payload.",
    }
  ]
}