ShareDoc:API documentation

Introduction

Share-VDE manages a complex domain composed by several entities. That results in a complex graph of interconnected entities that can be queried and used by external requestors through a rich set of public APIs. The purpose of this section is to describe what a requestor can do in terms of API in order to interact with Share-VDE.

We strongly recommend to experiment the Share-VDE API using the ready-to-use Postman collection.

This page offers a high-level overview of the Share-VDE public API, which are detailed in the following two sections:

• GraphQL API: GraphQL provides a front controller on top of heterogeneous data sources, whether the provider is an API, a database, or an arbitrary application that provides data through an interoperable protocol.
• REST: REST is a software architectural style which focuses on a resource-centric domain model.

Domain model (diagram)

At the heart of the system there's a complex domain model, as depicted in the following diagram:

The domain is composed by functional and technical entities, meaning with that a simple classification where we denote as

• "functional" those entities that are part of the Share-VDE Core Domain Model (e.g. Agents, Opuses, Works, Instances, Items)
• "technical" those entities required by some technical constraint in order to enrich the core entities with additional information (e.g. Collections, Facets, Pagination metadata).

Common Concepts

Before going ahead with the API description, it's important to centralise some concepts that are shared between the two available interfaces (GraphQL and REST).

• Simple Search: How the simple search works in Share-VDE, concepts and common behaviours

• Content Negotiation: Share-VDE resources are available in several formats, learn how to deal with the different representations
• Query Languages: there are multiple query languages available in Share-VDE. This section offers a detailed explanation about them.

The remaining part of this page describes other common things you should be aware before interacting with the API.

Pagination

All operations that return in response a collection of entities accept in input two optional parameters that allow to page the results.

Name	Type	Description	Default Value
rows	Integer	The size of the page of results in the response.	10
offset	Integer	The offset of the first item returned in results.	0

In response, the pagination parameters are returned back, together with a third information called totalMatches, which informs about the total number of entities matching the executed query. Here's an example

{
  "data": {
    "agents": {
      ...
      "totalMatches": 87,
      "pageSize": 10,
      "startOffset": 0
    }
  }
}

Sort

All operations that return in response a collection of entities accept an optional parameter that allow to sort the (paged) results.

Name	Type	Description	Default Value
sort	String	The sort clause (see below)	-----

The sort clause is composed by 2 parts:

• a field name: it must be marked as sortable in the Share-VDE dictionary.
• a sort order: asc (ascending) or desc (descending)

The following matrix lists, for each entity, the attributes available for sorting.

Sortable Attributes Matrix

	Contributor	Agent	Person	Meeting	Family	Organisation	Opus	Work	Instance	Item	Publication
name
beginningDate
endingDate
location
birthDate
deathDate
birthPlace
deathPlace
startDate
endDate
foundingYear
dissolutionYear
title
publicationYear
genre
language
form
placeOfOrigin
format
isbn
publicationType
publicationPlace
issn
ean
ismn
barcode
holdingInstitution
availability
callNo

Filters

All operations that return in response a collection of entities accept in input an optional multivalued parameter (i.e. an array) that allow to apply filters on the results. Specifically:

• in GraphQL API the parameter is called filters and it is an array of strings
• in RESTful API the parameter is a repeatable request parameter called filter

Name	Type	Description	Default Value
filters (GraphQL) / filter (REST)	String	A valid filter clause (see below)	-----

A filter clause is composed by 2 parts:

• a field name: The list of fields that can be used in a filter clause, for each entity, is provided in the sections that describe the available operations
• the colon operator :
• a valid clause: the following rules apply
  • In case of string or URI fields, the clause is the value we want to filter surrounded by double quotes
  • In case of numeric fields the value is just the value we want to use as a filter or a range (see below)

IMPORTANT

• multiple clause can be specified in one filter: in that case
  • they must refer to the same attribute
  • they must be separated using the OR keyword
  • the attribute (and the colon) must repeated for each value (e.g. year:1982 OR year:2020 OR year:1999)
• multiple filters (i.e. multiple parameters) are supposed to be executed in AND. That means the result is the global intersection of matching entities between the query and all filters

The following matrix lists, for each entity, the attributes available for filtering.

Filter Attributes Matrix

	Contributor	Agent	Person	Meeting	Family	Organisation	Opus	Work	Instance	Item	Publication
name
beginningDate
endingDate
location
birthDate
deathDate
birthPlace
deathPlace
occupation
startDate
endDate
foundingYear
dissolutionYear
year
genre
language
form
subject
placeOfOrigin
classification
publicationPlace
publicationYear
format
isbn
publicationType
issn
printOnline
ean
ismn
barcode
holdingInstitution
availability
callNo
contributor
printOnlineChoice
library
opusType
auctionExhibition
provenance
library

"library" and "provenance" filters

There are two filter attributes that can be used for filtering things belonging to a specific contributor institution: library and provenance.

• library is an attribute belonging to items; it is "artificially" copied into the corresponding item owning instance (during the indexing), and as consequence of that, it is available at instance or publication level. The typical usage scenario is when you may want to get back a list of publications (or instances) that have at least one item belonging to a given library/member/provenance.
• the provenance attribute has been introduced in SVDE-8447 (therefore in Share-VDE 3.0.0 and 2.5.0 or higher). It is on every core entity (i.e. Opus, Work, Instance, Item, Agent), it is a multivalued attribute and contains the list of provenances that contributed to a given entity. It can be used
  • in the /stats component, for retrieving counts by provenance
  • in contexts (see for example the NATBIB tenant) where there are no items in the knowledge base. In such a context the "library" attribute it is not available because as said above, it is derived from items.

REST Examples

Example #1: publications having 1982 as year

filter=publicationYear:1982

Example #2: publications having year between 1982 and 1999

filter=year:[1982 TO 1999]

Example #3: publications having year up to 1999

filter=year:[* TO 1999]

Example #4: publications having year from 1982

filter=year:[1982 TO *]

Example #5: publications having 1982 or 1999 as year

filter=year:1982 OR year:1999

Example #6: publications having 1982 or in range between 1999 and 2020

filter=year:1982 OR year:[1999 TO 2020]

Example #7: works having a specific language

filter=language:"https://svde.org/languages/ita"

Example #8: works having one or another language

filter=language:"https://svde.org/languages/ita" OR language:"https://svde.org/languages/fre"

Example #9: publications having a specific publication year and published in specific place

filter=publicationYear:1982&filter=language:"https://svde.org/places/28372837"

GraphQL Examples

Example #1: publications having 1982 as year

filters:["publicationYear:1982"]

Example #2: publications having year between 1982 and 1999

filters:["year:[1982 TO 1999]"]

Example #3: publications having year up to 1999

filters:["year:[* TO 1999]"]

Example #4: publications having year from 1982

filters:["year:[1982 TO *]”]

Example #5: publications having 1982 or 1999 as year

filters:["year:1982 OR year:1999"]

Example #6: publications having 1982 or in range between 1999 and 2020

filters:["year:1982 OR year:[1999 TO 2020]"]

Example #7: works having a specific language

filters:["language:\"https://svde.org/languages/ita\""]

Example #8: works having one or another language

filters:["language:\"https://svde.org/languages/ita\" OR language:\"https://svde.org/languages/fre\""]

Example #9: publications having a specific publication year and published in specific place

filters:["publicationYear:1982", "language:\"https://svde.org/places/28372837\""]