Last edited 6 months ago
by Serena Cericola

Share-VDE RESTful API

Revision as of 08:46, 28 May 2024 by Serena Cericola (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)


Introduction

Share-VDE exposes the resources that compose its Domain Model using a set of RESTful API. This page describes the REST interface in terms of entities, parameters and information related with this interaction mode.

The Share-VDE Domain is a mix of technical and functional entities that models the complex world needed for expressing the Share-VDE dataset. In this section we will detail those entities and their capabilities in terms of their REST interface.

Before going ahead, it's important to highlight a general assumption:

  • each Share-VDE entity is uniquely identified by a Share-VDE URI (e.g. https://svde.org/agents/201)

Hypermedia As The Engine Of Application State (HATEOAS)

Share-VDE resources provide information dynamically through hypermedia controls (links, in this specific case). A client obtains a resource representation which consists of the following:

  • literal attributes
  • links to other resources including itself

In that way, client actions are dynamically discovered directly in resource representations returned from the server: the links on a given resource representation provide the outgoing path for navigating the Share-VDE Domain Graph.

For example, starting from this resource that represents an agent (Lewis Carroll) the client can move to the associated Opuses using the links provided in the representation (note we have two links in this case for expressing the same path): 

"_links": {
...    
    "opuses": [
      {
        "href": "https://svde.org/agents/201/opuses"
      },
      {
        "href": "https://svde.org/people/201/opuses"
      }
    ],
...

which would lead to the list of opuses. There, each returned opus provides a set of outgoing links, including works, contributors, genre:

"_links": {
    ...
    "genre": {
        "href": "https://svde.org/genres/gf2015026020"
    },
    "contributors": {
        "href": "https://svde.org/opuses/401/contributors"
    },
    "works": {
        "href": "https://svde.org/opuses/401/works"
    }
          
}

Response Shape

A response can refers to three types of entities:

  • a single resource
  • a collection of resources
  • a paged collection of resources

Within the second and third response, each resource is represented using the first point.

Match Mode

The following endpoints

  • /resources
  • /agents
  • /opuses

return a paged collection with an additional meta section that informs the caller about the query match logic that has been executed. Here's an example: 

{
  "_embedded": {
    "resourceList": [
      ... (paged resource list)
    ]
  },
  ...
  "meta": {
    "matchMode": "FULL"
  }
}

Possible values of the matchMode meta attribute are:

  • FULL: it indicates that an AND logic between query terms has been applied
  • PARTIAL: it indicates that an OR logic between query terms has been applied
  • SERVER_DEFINED: (advanced search only) when the search logic that has been executed cannot be summarised/simplified using the mnemonic codes above.
  • USER_DEFINED: in case of simple search where at least one query term is prefixed by a mandatory (+) or unwanted (-) modifier.

Explanation

A virtual entity, connected to a core entity (e.g. Agent, Opus) which provides insights about the reason why a given resource has been included in (simple) search results.

The explanation is typically requested on a given search result, after a query execution. Here's an example flow:

  1. Simple search using one or more terms (e.g. history republic 1972)
  2. Query response including entities E1, E2, E3
  3. (on demand) Explain for E1
  4. (on demand) Explain for E2
  5. (on demand) Explain for E3

Endpoints

/{plural form of entityType}/{id}/explanation

Returns the explanation for the entity associated to the input identifier. The path variable are

  • {plural form of entity type}: opuses, agents, people, organisations, meetings, families, instances (for publications)
  • {id}: the internal resource identifier

Examples

/opuses/401/explanation?terms=lewis carroll

/agents/201/explanation?terms=daresbury

/people/201/explanation?terms=daresbury

Response

Returns a single resource which consists of the requested explanation (i.e. highlighting snippets of the matching terms).

Each snippets refers to a specific attribute which follows these rules

  • it contains the matching terms highlighted (e.g. surrounded by a "bold" html marker
/organisations/101/explanation?terms=american%20library

{
  "meta": {
    "aut": {
      "label": "author",
      "language": "eng",
      "type": "Role"
    }
  },
  "aut": [
    {
      "title": "<b>Library</b> media & information skills"
    },
    {
      "titleAlternative": "<b>Library</b> media and information skills"
    }
  ],
  "name": "<b>American</b> <b>Library</b> Association",
  ...
}
  • in case the language is available it is included beside the value
/people/201/explanation?terms=daresbury

{
  "birthPlace": {
    "label": {
      "value": "<b>Daresbury</b>",
      "language": "eng"
    }
  },
  ...
}
  • in case the language is "und" (undefined) it is not included in the value
  • it can be nested, when the attribute is indirect (i.e. it doesn't belong directly to the requested entity). Each part of the attribute name can represent
    • the attribute name itself (e.g. nameAlternative, label, altLabel)
    • the referred nested entity (e.g. instance, work)
    • the relator code (e.g. aut = author, ill = illustrator, pbl = publisher)
    • the subject type code (e.g. top = topical subject, nameSubject = name subject)

In the last two cases (relator code or subject type), the response contains also a meta section which informs about its meaning. In the following example the meta section describes the "pbl" identifiers and provides three metadata attributes:

  • the human readable label
  • the language of the label
  • the entity type (e.g. Role, SubjectType)
/opuses/411/explanation?terms=georgia%20press

{
  "meta": {
    "pbl": {
      "label": "Publisher",
      "language": "eng",
      "type": "Role"
    }
  },    
  "instance": [
    {
      "pbl": {
        "nameAlternative": "University of <b>Georgia</b> <b>Press</b> American publisher"
      }
    },
    {
      "publicationPlace": {
        "label": {
          "value": "Athens i <b>Georgia</b>",
          "language": "nno"
        }
      }
    },
    {
      "pbl": {
        "name": "University of <b>Georgia</b> <b>press</b>"
      }
    }
  ],
  ...
}
Examples
Agents

Example #1: Agent explanation: name and birth date

Terms are found in this example only among the direct attributes of the agent

Example #2: Agent explanation: english preferred form of birth place

The nested structure is because the birthPlace is an entity (Place) which can potentially have several matching attributes ("label" in this example)

Example #3: Agent explanation: english preferred and alternative form of birth place

Here's an example of two indirect attributes matching the requested terms (label and altLabel)

Example #4: Agent explanation: english preferred and alternative form of birth place (boolean operator)

Boolean operators can be used between terms (the AND operator in the example makes both terms mandatory)

Example #5: Agent explanation: english alternative form of birth place (phrase query)

Terms surrounded by double quotes trigger the so called "proximity search"

Example #6: Agent explanation: english preferred form of death place

Example #7: Agent explanation: latin preferred form of death place

Example #8: Agent explanation: english preferred form of occupation

Example #9: Agent explanation: italian preferred form of occupation

Example #10: Agent explanation: english alternative form of occupation

Example #11: Agent explanation: related Opus (headings) and agent role (author).

People

Example #1: Person explanation: name and birth date

Example #2: Person explanation: english preferred form of birth place

Example #3: Person explanation: english preferred and alternative form of birth place

Example #4: Person explanation: english alternative form of birth place (phrase query)

Example #5: Person explanation: english preferred form of death place

Example #6: Person explanation: latin preferred form of death place

Example #7: Person explanation: english preferred form of occupation

Example #8: Person explanation: italian preferred form of occupation

Example #9: Person explanation: english alternative form of occupation

Organisations

Example #1: Organisation explanation: italian preferred form of location

Opuses

Example #2: Opus explanation: english preferred form of genre

Example #3: Opus explanation: Hungarian preferred form of genre

Example #4: Opus explanation: english alternative form of genre

Example #5: Opus explanation: author name (in agent name and instance title)

Example #6: Opus explanation: topical subject

Example #7: Opus explanation: name subject (the example includes also the author)

Example #8: Opus explanation: illustrator (work contributor) data

Example #9: Opus explanation: (work) classification

Example #10: Opus explanation: (instance) publication year

Example #11: Opus explanation: publication place

Example #12: Opus explanation: publisher (instance contributor) data

Resource

A resource returned in a response is represented using two sets of attributes:

  • direct attributes whose values are literals (e.g. strings, numbers)
  • links that point to the linked resources
{
  "preferredHeading": "Carroll, Lewis",
  "alternateHeadings": [
    "Karol, Luis",
    "Dodgson, Charles Lutwìdge"
  ],
  "birthDate": 1832,
  "deathDate": 1898,
  "_links": {
...

note the links includes also references to the resource itself. Those references, in a special section called "self" could be

  • Share-VDE URIs
  • External URIs: in this a "type" attribute indicates the source:
"_links": {
    "self": [
      {
        "href": "https://svde.org/people/201"
      },
      {
        "href": "https://svde.org/agents/201"
      },
      {
        "href": "https://www.wikidata.org/wiki/Q38082",
        "type": "wikidata"
      },
      {
        "href": "http://isni.org/isni/000000012137136X",
        "type": "isni"
      },
      {
        "href": "https://viaf.org/viaf/66462036/",
        "type": "viaf"
      }
    ],

Collection

A list of resources with a predefined and relatively small size. The only example we have at the moment is the collection of occupations associated with a given person:

{
  "_embedded": {
    "occupationList": [
      {
        "preferredHeading": "Matematician",
        "language": "en",
        "_links": {
          "self": [
            {
              "href": "http://dbpedia.org/page/Matematician",
              "type": "other"
            },
            {
              "href": "https://svde.org/occupations/Matematician"
            },
            {
              "href": "https://svde.org/people/201/occupations/Matematician"
            }
          ],
          "Person": {
            "href": "https://svde.org/people/201"
          }
        }
      },
      {
        "preferredHeading": "Teacher",
        ...
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://uat3-base-svde.atcult.it/people/201/occupations"
    },
    "Person": {
      "href": "https://uat3-base-svde.atcult.it/people/201"
    }
  }
}

As you can see, the collection is a simple list of resources. In addition, it provides two top level links:

  • a link to the collection itself (self)
  • a link to the owning entity (the person)

Paged Collection

Usually collections, especially those that are returned in response after executing a search, include a lot of matching resources that are not returned in a single shot. Instead, a page of those matching resources are returned according to some pagination parameters.

A paged collection, as the name suggests, is a sublist of resources matching a given search and refine criteria. Specifically:

  • the search can be a fulltext search (e.g. give me all agents whose name is andrea) or a boolean (e.g. give me all opuses where the agent XYZ is the author)
  • search results can be refined by using one or more filters (e.g. filter by a specific publication year)
  • search results can be sorted by a given criteria. In case of fulltext search the default sort criterion is by relevance

The response contains 3 sections:

  • the page including the resources. Each resource is represented according to its type following what we described previously
  • pagination metadata: three attributes (totalMatches, pageSize and startOffset)
  • facets: aggregations over the entity attributes. Facets depend on the type of the returned entities
{
  "_embedded": {
    "agentList": [
      {
        "preferredHeading": "Carroll, Adam (Adam Paul)",
        "alternateHeadings": [
          "Carroll, Adam Paul"
        ],
        ...
      },
      ...other resources follow
    ]
  },
  ...
  "facets": {
    "birthPlace": {
      "https://svde.org/places/7295222": 2,
      "https://svde.org/places/2643743": 1
    },
    "occupation": {
      "https://svde.org/occupations/Teacher": 2,
      "https://svde.org/occupations/Historian": 1,
      "https://svde.org/occupations/Matematician": 1,
      "https://svde.org/occupations/Producer": 1,
      "https://svde.org/occupations/Writer": 1
    },
    "deathPlace": {
      "https://svde.org/places/3169070": 2,
      "https://svde.org/places/998610": 1
    },
    "deathDate": {
      "1893": 1,
      "1898": 1
    },
    "birthDate": {
      "1832": 1,
      "1833": 1
    }
  },
  "page": {
    "totalMatches": 3,
    "startOffset": 0,
    "pageSize": 3
  }
}

Bibliographic and Authority record lists

Every core entity in Share-VDE's RESTful API exposes its source records (either of Bibliographic and Authority type) with dedicated endpoints.

Basically, those endpoints are aimed to:

  1. obtain the list of source records that contributed to form the entity's shape;
  2. obtain the single source record using its local ID as the URI.

On top of that, endpoints belonging to point 1. can work according to 2 different behaviors. In fact, the list of source records that formed an entity can be requested in full (using the representation of choice, see the Content Negotiation chapter, e.g. marcxml or mrc) thus obtaining the records themselves in the requested form, or in its short version (that we friendly call shortlist), i.e. a JSON HATEOAS representation of the entity's records metadata, useful for users as a quick guide to inspect which records affect the selected entity.

The shortlist can be obtained adding to the entity's /records URI segment the full=false parameter, just like in this example: 

https://svde.org/opuses/1234567890/records?full=false

The resulting shortlist will be:

{
    "_embedded": {
        "resourceList": [
            {
                "localId": "013681601",
                "sourceType": "BIB",
                "_links": {
                    "clusterUri": {
                        "href": "https://svde.org/opuses/1234567890"
                    },
                    "provenance": {
                        "href": "https://svde.org/agents/UCHICAGO"
                    },
                    "recordUrlMarc": {
                        "href": "https://svde.org/opuses/1234567890/records/013681601.mrc"
                    },
                    "recordUrlMarcXml": {
                        "href": "https://svde.org/opuses/1234567890/records/013681601.marcxml"
                    }
                }
            },
            {
                "localId": "no91011934",
                "sourceType": "AUT",
                "_links": {
                    "clusterUri": {
                        "href": "https://svde.org/opuses/1234567890"
                    },
                    "provenance": {
                        "href": "https://svde.org/agents/STANFORD"
                    },
                    "recordUrlMarc": {
                        "href": "https://svde.org/opuses/1234567890/records/no91011934.mrc"
                    },
                    "recordUrlMarcXml": {
                        "href": "https://svde.org/opuses/1234567890/records/no91011934.marcxml"
                    }
                }
            }
        ]
    },
    "_links": {
        "self": {
            "href": "http://svde.org/opuses/1234567890/records?full=false"
        }
    }
}

Endpoints

Share-VDE resources are not publicly exposed: we classified the available endpoints in two main categories:

  • Search API: this category includes all endpoints that are part of the Share-VDE Search API: they require a caller having a minimal role level (svde-reader)
  • Curation API: this category includes the access to those resources that are part of Share-VDE Curation API. Due to the level of information exposed, the access to these resources require at least a basic editing role capabilities (i.e. svde-editor-base or higher)

Search API

This category includes all endpoints that are part of the Share-VDE Search API: they require a caller having a minimal role level (svde-reader).

The available endpoints are detailed in this page.

Retrieved from "https://wiki.share-vde.org/w/index.php?title=ShareDoc:RESTFul_API&oldid=2493"