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[1] 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[2] 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 consolidate 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 additional details 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.
| 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.
| 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\""]
