API Documentation
Overview
A system to manage, allow querying and provide information about Getty resources and how they relate to other resources or identifiers. The resources can be identified using local system identifiers, 'slug' identifiers, URIs or by universal unique identifiers (UUID). The smallest unit of information is a annotation known as a "link", which is based the Web Annotation Data Model and is a constrained form of a Web Annotation (the 'related to' part of the model is referred to as the 'motivation')
The ID Manager tool allows users to query data on links between identified resources. A query will provide a pattern for the link and the service will return a list of all links that match that pattern exactly. Each link is a Web Annotation but it only supports the following parts and has some additional constraints not present in the model (see above)
A Link (annotation):
- An annotation MUST contain a body (with an URI ID and a 'generator'), a target (with an URI ID and a 'generator' as well) and a motivation (concept, reason for the link).
- A generator is a URI that represents whichever system manages or is responsible for creating the ID. Also, the ID management software enforces a closed list of possible generator and motivation URIs. The body and target can also have an optional 'format' which is a mimetype for the resource it describes.
- id (mandatory, automatic)
- created/modified (mandatory, automatic)
- label (optional, holds the 'group_id)
- dcterms:title (optional)
- dcterms:alternative (optional)
- creator (optional, can only be assigned a
{"name": "...."}structure.)
NB Textual bodies and other range content are not supported.
Using the system
There are two main routes to query and input links into the service - through the API, and through the web interface.
Web Interface: (pictoral overview) The service does provide an HTML view to clients that request it, using a web browser for example. The pages were added to make navigating, viewing and querying the data much easier and to make it more readable, as web browsers (and people) do not have a good way of interpreting JSON-LD data natively. The interface also provides basic forms to create, edit or delete data at a low-level, and at the scope of a single link, as sometimes it is necessary to make a small change, or to add a link that is missing. It is not intended to replace the API routes, and it is not purposed to support any particular workflow.
Python Client/API: The API is based on REST principles and additionally has some RPC endpoints primarily for bulk additions and deletions. The query endpoint responds to a query with a list of the matching links, formatted as JSON-LD, using the Web Annotation Model's AnnotationCollection so that large responses can be retrieved quickly as a paginated set of results. A python client library has been written to simplify things, so that specific knowledge of how the API works is not necessary - a prebuilt version is available through the Nexus repository, and the section on using the client will assume that this package is available through that route
Building and deploying
Building this project currently requires access to the Getty Nexus repository, but can be run from as a docker image.
Overview of build and deployment options
License and Copyright
(c) The J. Paul Getty Trust. All rights reserved.