API Documentation

API - Groups

Allows for bulk actions to be taken on links tagged with a particular group_id, as well as providing a list of currently entered group identifiers in the system.

Get All Groups

This will get the entire list of all groups registered in the system. This request may take a considerable amount of time on a large system. This is of use only for administrative purposes and will not be of use outside of that.

URL : /groups/

Method : GET

Auth required : No

HTML/JSON : JSON

Success Responses

Code : 200 OK

Content example : Returns a simple JSON response that lists all of the group identifiers in the system.

copy{ 
  "groups": ['groupid1', 'groupid2', ..., 'testdatagroup', 'rosetta:/IE12345']
}

GET /groups/

This endpoint acts and response in highly similar manner to the GET /links/ endpoint mentioned above, but the AnnotationCollection response generated will be filtered to only contain links that are tagged with the matching group_id. eg looking for iiif_canvas_of relationships in the 'testdata' group (random link data can be generated and will be tagged with this group id):

GET /groups/testdata?motivation=https://data.getty.edu/local/thesaurus/motivations/iiif_canvas_of

copy  {
    "@context": "http://www.w3.org/ns/anno.jsonld",
    "first": {
        "id": "http://localhost:5001/id-management/groups/testdata/page/1?group_id=testdata&motivation=https%3A//data.getty.edu/local/thesaurus/motivations/iiif_canvas_of",
        "items": [
            {
                "body": {
                    "generator": "https://data.getty.edu/local/thesaurus/generators/otmm",
                    "id": "a}AEQ?vB:@b',g!A?B|$vJo[NWMs/IB+Hx3j{B0DbAL+0M",
                    "format": None
                },
                "created": "2020-10-29T23:23:53",
                "id": "http://localhost:5001/id-management/links/73c247dc-53c6-4818-b41a-a99520d4d2e2",
                "label": "testdata",
                "dcterms:title": "Test Title",
                "dcterms:alternative": "Test Reverse Title",
                "modified": "2020-10-29T23:23:53",
                "creator": {
                  "name": "Test User"
                },
                "motivation": "https://data.getty.edu/local/thesaurus/motivations/iiif_canvas_of",
                "target": {
                    "generator": "https://data.getty.edu/local/thesaurus/generators/otmm",
                    "id": "J,$|!-BuO9"
                },
                "type": "Annotation"
            },
            {
            // RESPONSE ITEMS OMITTED
            }
        ],
        "startIndex": 0,
        "type": "AnnotationPage"
    },
    "id": "http://localhost:5001/id-management/groups/testdata/?group_id=testdata&motivation=https%3A//data.getty.edu/local/thesaurus/motivations/iiif_canvas_of",
    "label": "Collection of Link Annotations for [[('group_id', 'testdata'), ('motivation', 'https://data.getty.edu/local/thesaurus/motivations/iiif_canvas_of')]]",
    "last": "http://localhost:5001/id-management/groups/testdata/page/1?group_id=testdata&motivation=https%3A//data.getty.edu/local/thesaurus/motivations/iiif_canvas_of",
    "total": 15,
    "type": "AnnotationCollection"
}

Get All links for a group

This endpoint acts and response in a similar manner to the query links endpoint, but the AnnotationCollection response generated will be filtered to only contain links that are tagged with the matching group_id. eg looking for iiif_canvas_of relationships in the 'testdata' group (random link data can be generated and will be tagged with this group id):

URL : /groups/{group_id}

URL : /groups/{group_id}/page/{page_number} (for pagination of results)

Method : GET

Auth required : No

HTML/JSON : Both

Success Responses

Code : 200 OK

Please see the query links output format documentation for details.

Error Response

Condition : If there is no such group.

Code : 404 Not Found

Delete all links in a group

This is a powerful feature and will delete any link that matches the provided group_id. This requires authentication and while extremely useful and quick compared to deleting links individually, there is no undo short of a database recovery from backup.

This is a good way to 'update' a set of links created by a process when you do not have or want to have a record of the links created the previous time the process was run. Deleting the group and readding a freshly created list of links to 'replace' the group is a common pattern.

URL : /groups/{group_id}

Method : DELETE

Auth required : YES

HTML/JSON : JSON

Success Responses

Condition : Group ID exists and User is Authenticated.

Code : 200 OK