==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.

At the heart of the system there's a '''complex domain model,''' as depicted in the following diagram:[[File:Share VDE Domain Model.png|alt=Share VDE Domain Model|left|thumb]]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).

=== Knowledge Base, Tenants, Provenances ===
'''Share-VDE''' manages a '''Knowledge Base''' which consists of '''clustered''', '''integrated''' and '''enriched entities'''. In Share-VDE, a '''tenant''' is represented by a set of '''institutions''' contributing to the '''same Knowledge base'''.
[[File:svde-ckb-provenance-tenant.png|none|thumb]]
An institution '''Pn''' within a tenant is called '''provenance'''. We use that term because we always want to '''retain''' the '''relationship''' between '''Share-VDE entities''' and '''data''' that '''originally contributed''' to their building.

===Multiple Tenants? The Share-VDE Family===
Multiple tenants form the '''Share Family'''. Family members interoperate through a centralised registry.
[[File:share-family.png|none|thumb]]

===Share-VDE Entities===
In the following diagram we depicted a high-level overview of the clusters genesis process.
[[File:data-to-svde-clusters.png|none|thumb|589x589px]]
Starting from the left side we have:

*A '''tenant''' composed by n institutions (P1...Pn)
*'''Institutions''' '''contribute''' with their raw '''data''' (e.g. bibliographic records, authority records)
*The '''Share-VDE clusters''' are created in the '''Knowledge Base''' by means of an automatic process we simply call '''"clustering"'''

===The Share-VDE Entity: The Prism===
Each Share-VDE cluster is the result of merging contributions from several sources, including a special enrichment for linking external sources (e.g. VIAF, ISNI).

We like to imagine a cluster like a prism, which is a whole unit and at the same time it retains several faces (the contribution of each source). See the following diagrams for a visual explanation
[[File:prism 1.png|none|thumb|424x424px]]
[[File:prism 2.png|none|thumb|425x425px]]
===API Perspective===
Each cluster type has a '''"provenances"''' field associated which, as the name suggests, indicates the '''provenances that contributed''' to that cluster definition.

Here's an example of a request which asks for a specific Person and its provenances:<syntaxhighlight lang="json">
{
person(uri: "https://svde.org/agents/201") {
uri
name
provenances {
uri
description
}
}
}
</syntaxhighlight>In the response below we clearly see the '''Share-VDE cluster''' for Luiss Carroll has been '''contributed''' by '''3 institutions''': Stanford, Alberta and British Library. <syntaxhighlight lang="json">
{
"data": {
"person": {
"uri": "https://svde.org/agents/201",
"name": "Carroll, Luiss",
"provenances": [
{
"uri": "https://svde.org/agents/STANFORD",
"description": "Stanford University"
},
{
"uri": "https://svde.org/agents/BL",
"description": "British Library"
},
{
"uri": "https://svde.org/agents/UALBERTA",
"description": "University of Alberta"
}
]
}
}
}
</syntaxhighlight>

ShareDoc:Domain Model

2023-12-22T20:04:58Z

Andrea Gazzarini:

ShareDoc:Domain Model

2023-12-22T20:03:54Z

Andrea Gazzarini: Created page with "==Introduction== '''Share-VDE''' manages a '''Knowledge Base''' which consists of '''clustered''', '''integrated''' and '''enriched entities'''. In Share-VDE, a '''tenant''' i..."

==Introduction==
'''Share-VDE''' manages a '''Knowledge Base''' which consists of '''clustered''', '''integrated''' and '''enriched entities'''. In Share-VDE, a '''tenant''' is represented by a set of '''institutions''' contributing to the '''same Knowledge base'''.
[[File:svde-ckb-provenance-tenant.png|none|thumb]]
An institution '''Pn''' within a tenant is called '''provenance'''. We use that term because we always want to '''retain''' the '''relationship''' between '''Share-VDE entities''' and '''data''' that '''originally contributed''' to their building.

===Multiple Tenants: The Share-VDE Family===
Multiple tenants form the '''Share Family'''. Family members interoperate through a centralised registry.
[[File:share-family.png|none|thumb]]

===Share-VDE Clusters: The Genesis===
In the following diagram we depicted a high-level overview of the clusters genesis process.
[[File:data-to-svde-clusters.png|none|thumb|589x589px]]
Starting from the left side we have:

*A '''tenant''' composed by n institutions (P1...Pn)
*'''Institutions''' '''contribute''' with their raw '''data''' (e.g. bibliographic records, authority records)
*The '''Share-VDE clusters''' are created in the '''Knowledge Base''' by means of an automatic process we simply call '''"clustering"'''

===The Share-VDE Cluster: The Prism===
Each Share-VDE cluster is the result of merging contributions from several sources, including a special enrichment for linking external sources (e.g. VIAF, ISNI).

We like to imagine a cluster like a prism, which is a whole unit and at the same time it retains several faces (the contribution of each source). See the following diagrams for a visual explanation
[[File:prism 1.png|none|thumb|424x424px]]
[[File:prism 2.png|none|thumb|425x425px]]
===Prism Status List===
{| class="wikitable"
!'''Status Code'''
!'''Description'''
!Locking?
|-
|SV or Null/Empty
|Saved
|No
|-
|ED
|Edit
|No
|-
|MS
|Merge Source (the prism is part of a merge list as merge source)
|Yes
|-
|MD
|Merge Destination (the prism is part of a merge list as merge destination)
|Yes
|-
|SG
|Split Giver
|Yes
|-
|SR
|Split Receiver
|Yes
|-
|NV
|Invalidated
|Yes
|-
|RN
|Review Needed
|Yes
|}

===API Perspective===
Each cluster type has a '''"provenances"''' field associated which, as the name suggests, indicates the '''provenances that contributed''' to that cluster definition.

Here's an example of a request which asks for a specific Person and its provenances:<syntaxhighlight lang="json">
{
person(uri: "https://svde.org/agents/201") {
uri
name
provenances {
uri
description
}
}
}
</syntaxhighlight>In the response below we clearly see the '''Share-VDE cluster''' for Luiss Carroll has been '''contributed''' by '''3 institutions''': Stanford, Alberta and British Library. <syntaxhighlight lang="json">
{
"data": {
"person": {
"uri": "https://svde.org/agents/201",
"name": "Carroll, Luiss",
"provenances": [
{
"uri": "https://svde.org/agents/STANFORD",
"description": "Stanford University"
},
{
"uri": "https://svde.org/agents/BL",
"description": "British Library"
},
{
"uri": "https://svde.org/agents/UALBERTA",
"description": "University of Alberta"
}
]
}
}
}
</syntaxhighlight>The request/response above depicts an '''interaction''' between an '''anonymous''' (i.e. read-only) requestor and Share-VDE. In case the client has '''write permissions''' (e.g. it is associated to a '''svde-editor''' or '''svde-editor-advanced'''), for each provenance it's possible to get information about '''users''' (belonging to that provenance) '''that are working on that cluster'''.
The request includes in this case a "status" field: <syntaxhighlight lang="json">
{
person(uri: "https://svde.org/agents/201") {
uri
name
provenances {
uri
description
status {
statusCode
user {
username
fullName
}
}
}
}
}
</syntaxhighlight>The response contains now the information about three users that are editing that cluster:<syntaxhighlight lang="json">
{
"data": {
"person": {
"uri": "https://svde.org/agents/201",
"name": "Carroll, Luiss",
"provenances": [
{
"uri": "https://svde.org/agents/UALBERTA",
"status": [
{
"statusCode": "ED",
"user": {
"username": "agazzarini",
"fullName": "Andrea Gazzarini"
}
},
{
"statusCode": "ED",
"user": {
"username": "mbranca",
"fullName": "Max Branca"
}
}
]
},
{
"uri": "https://svde.org/agents/BL",
"status": []
},
{
"uri": "https://svde.org/agents/STANFORD",
"status": [
{
"statusCode": "ED",
"user": {
"username": "fzancan",
"fullName": "Federico Zancan"
}
}
]
}
]
}
}
}
</syntaxhighlight>

ShareDoc:API documentation

2023-12-22T20:02:10Z

Andrea Gazzarini:

{{DISPLAYTITLE:Share-VDE APIs}}

__TOC__
__FORCETOC__

==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 [[ShareVDEmembers:TechnicalDocumentation/The PostMan Collection|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:

*[[ShareDoc:GraphQL API|GraphQL API:]] GraphQL<ref>https://graphql.org/</ref> 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.
*[[ShareVDEmembers:APIdoc/RESTFul API|REST]]: REST<ref>https://en.wikipedia.org/wiki/Representational_state_transfer</ref> 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:
[[File:Share VDE Domain Model.png|alt=Share VDE Domain Model|left|thumb]]
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 ([[ShareDoc:GraphQL API|GraphQL]] and [[ShareVDEmembers:APIdoc/RESTFul API|REST]]).

*[[ShareVDEmembers:Simple Search|Simple Search:]] How the simple search works in Share-VDE, concepts and common behaviours

*[[ShareVDEmembers:TechnicalDocumentation/Content Negotiation|Content Negotiation]]: Share-VDE resources are available in several formats, learn how to deal with the different representations
*[[ShareVDEmembers:APIdoc/Query Languages|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.
{| class="wikitable" style=""
!'''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<syntaxhighlight lang="json">
{
"data": {
"agents": {
...
"totalMatches": 87,
"pageSize": 10,
"startOffset": 0
}
}
}
</syntaxhighlight>
=== Sort===
All operations that return in response a collection of entities accept an optional parameter that allow to sort the (paged) results.
{| class="wikitable" style=""
!'''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.
{| class="wikitable" style=""
|+
Sortable Attributes Matrix
!
!'''Contributor'''
!'''Agent'''
!'''Person'''
!'''Meeting'''
!'''Family'''
!'''Organisation'''
!'''Opus'''
!'''Work'''
!'''Instance'''
!'''Item'''
!'''Publication'''
|-
|'''name'''
| style="background-color:;" class="col-green-bg" |
| style="background-color:;" class="col-green-bg" |
| style="background-color:;" class="col-green-bg" |
| style="background-color:;" class="col-green-bg" |
| style="background-color:;" class="col-green-bg" |
| style="background-color:;" class="col-green-bg" |
|
|
|
|
|
|-
|'''beginningDate'''
| style="background-color:;" class="col-green-bg" |
| style="background-color:;" class="col-green-bg" |
|
|
|
|
|
|
|
|
|
|-
|'''endingDate'''
| style="background-color:;" class="col-green-bg" |
| style="background-color:;" class="col-green-bg" |
|
|
|
|
|
|
|
|
|
|-
|'''location'''
|
|
|
| style="background-color:;" class="col-green-bg" |
|
| style="background-color:;" class="col-green-bg" |
|
|
|
|
|
|-
|'''birthDate'''
|
|
| style="background-color:;" class="col-green-bg" |
|
|
|
|
|
|
|
|
|-
|'''deathDate'''
|
|
| style="background-color:;" class="col-green-bg" |
|
|
|
|
|
|
|
|
|-
|'''birthPlace'''
|
|
| style="background-color:;" class="col-green-bg" |
|
|
|
|
|
|
|
|
|-
|'''deathPlace'''
|
|
| style="background-color:;" class="col-green-bg" |
|
|
|
|
|
|
|
|
|-
|'''startDate'''
|
|
|
|
| style="background-color:;" class="col-green-bg" |
|
|
|
|
|
|
|-
|'''endDate'''
|
|
|
|
| style="background-color:;" class="col-green-bg" |
|
|
|
|
|
|
|-
|'''foundingYear'''
|
|
|
|
|
| style="background-color:;" class="col-green-bg" |
|
|
|
|
|
|-
|'''dissolutionYear'''
|
|
|
|
|
| style="background-color:;" class="col-green-bg" |
|
|
|
|
|
|-
|'''title'''
|
|
|
|
|
|
| style="background-color:;" class="col-green-bg" |
|
| style="background-color:;" class="col-green-bg" |
|
| style="background-color:;" class="col-green-bg" |
|-
|'''publicationYear'''
|
|
|
|
|
|
| style="background-color:;" class="col-green-bg" |
| style="background-color:;" class="col-green-bg" |
|
|
| |
|-
|'''genre'''
|
|
|
|
|
|
| |
|
|
|
| |
|-
|'''language'''
|
|
|
|
|
|
|
| style="background-color:;" class="col-green-bg" |
|
|
| style="background-color:;" class="col-green-bg" |
|-
|'''form'''
|
|
|
|
|
|
|
| style="background-color:;" class="col-green-bg" |
|
|
| style="background-color:;" class="col-green-bg" |
|-
|'''placeOfOrigin'''
|
|
|
|
|
|
|
| style="background-color:;" class="col-green-bg" |
|
|
| style="background-color:;" class="col-green-bg" |
|-
|'''format'''
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-green-bg" |
|
| style="background-color:;" class="col-green-bg" |
|-
|'''isbn'''
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-green-bg" |
|
| style="background-color:;" class="col-green-bg" |
|-
|'''publicationType'''
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-green-bg" |
|
| style="background-color:;" class="col-green-bg" |
|-
|'''publicationPlace'''
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-green-bg" |
|
| style="" |
|-
|'''issn'''
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-green-bg" |
|
| style="background-color:;" class="col-green-bg" |
|-
|'''ean'''
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-green-bg" |
|
| style="background-color:;" class="col-green-bg" |
|-
|'''ismn'''
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-green-bg" |
|
| style="background-color:;" class="col-green-bg" |
|-
|'''barcode'''
|
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-green-bg" |
|
|-
|'''holdingInstitution'''
|
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-green-bg" |
|
|-
|'''availability'''
|
|
|
|
|
|
|
|
|
|
|
|-
|'''callNo'''
|
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-green-bg" |
|}

===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 [[ShareDoc:GraphQL API|GraphQL]] API the parameter is called '''filters''' and it is an array of strings
* in [[ShareVDEmembers:APIdoc/RESTFul API|RESTful]] API the parameter is a repeatable request parameter called '''filter'''

{| class="wikitable" style=""
!'''Name'''
!'''Type'''
!'''Description'''
!'''Default Value'''
|-
|filters ([[ShareDoc:GraphQL API|GraphQL]]) / filter ([[ShareVDEmembers:APIdoc/RESTFul API|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.
{| class="wikitable" style=""
|+'''Filter Attributes Matrix'''
!
!'''Contributor'''
!'''Agent'''
!'''Person'''
!'''Meeting'''
!'''Family'''
!'''Organisation'''
!'''Opus'''
!'''Work'''
!'''Instance'''
!'''Item'''
!'''Publication'''
|-
|'''name'''
| |
| |
| |
| |
| |
| |
|
|
|
|
|
|-
|'''beginningDate'''
| style="background-color:;" class="col-orange-bg" |
| style="background-color:;" class="col-orange-bg" |
|
|
|
|
| |
|
|
|
|
|-
|'''endingDate'''
| style="background-color:;" class="col-orange-bg" |
| style="background-color:;" class="col-orange-bg" |
|
|
|
|
|
| |
|
|
|
|-
|'''location'''
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
| style="background-color:;" class="col-orange-bg" |
|
|
|
|
|
|-
|'''birthDate'''
| |
|
| style="background-color:;" class="col-orange-bg" |
|
|
|
|
|
|
|
|
|-
|'''deathDate'''
|
|
| style="background-color:;" class="col-orange-bg" |
|
|
|
|
|
|
|
|
|-
|'''birthPlace'''
|
|
| style="background-color:;" class="col-orange-bg" |
|
|
|
|
|
|
|
|
|-
|'''deathPlace'''
|
|
| style="background-color:;" class="col-orange-bg" |
|
|
|
|
|
|
|
|
|-
|'''occupation'''
|
|
| style="background-color:;" class="col-orange-bg" |
|
|
|
|
|
|
|
|
|-
|'''startDate'''
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
|
|
|
|
|
|-
|'''endDate'''
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
|
|
|
|
|
|-
|'''foundingYear'''
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
|
|
|
|
|-
|'''dissolutionYear'''
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
|
|
|
|
|-
|'''year'''
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
|
|
|
|-
|'''genre'''
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
|
|
| style="background-color:;" class="col-orange-bg" |
|-
|'''language'''
|
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
|
| style="background-color:;" class="col-orange-bg" |
|-
|'''form'''
|
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
|
| style="background-color:;" class="col-orange-bg" |
|-
|'''subject'''
|
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
|
| style="background-color:;" class="col-orange-bg" |
|-
|'''placeOfOrigin'''
|
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
|
| style="background-color:;" class="col-orange-bg" |
|-
|'''classification'''
|
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
|
| style="background-color:;" class="col-orange-bg" |
|-
|'''publicationPlace'''
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
| style="background-color:;" class="col-orange-bg" |
|-
|'''publicationYear'''
|
|
|
|
|
| style="background-color:;" class="col-white-bg" |
|
|
| style="background-color:;" class="col-orange-bg" |
|
| style="background-color:;" class="col-orange-bg" |
|-
|'''format'''
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
| style="background-color:;" class="col-orange-bg" |
|-
|'''isbn'''
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
| style="background-color:;" class="col-orange-bg" |
|-
|'''publicationType'''
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
| style="background-color:;" class="col-orange-bg" |
|-
|'''issn'''
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
| style="background-color:;" class="col-orange-bg" |
|-
|'''printOnline'''
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
| style="background-color:;" class="col-orange-bg" |
|-
|'''ean'''
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
| style="background-color:;" class="col-orange-bg" |
|-
|'''ismn'''
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
| style="background-color:;" class="col-orange-bg" |
|-
|'''barcode'''
|
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
| style="background-color:;" class="col-orange-bg" |
|-
|'''holdingInstitution'''
|
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
| style="background-color:;" class="col-orange-bg" |
|-
|'''availability'''
|
|
|
|
|
|
|
|
|
|
|
|-
|'''callNo'''
|
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
| style="background-color:;" class="col-orange-bg" |
|-
|'''contributor'''
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
| style="background-color:;" class="col-orange-bg" |
| style="background-color:;" class="col-orange-bg" |
|
| style="background-color:;" class="col-orange-bg" |
|-
|'''printOnlineChoice'''
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
| style="background-color:;" class="col-orange-bg" |
|-
|'''library'''
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
| style="background-color:;" class="col-orange-bg" |
|-
|'''opusType'''
|
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
| style="background-color:;" class="col-orange-bg" |
|
| style="background-color:;" class="col-orange-bg" |
|-
|'''auctionExhibition'''
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
| style="background-color:;" class="col-orange-bg" |
|-
|'''provenance'''
|
| style="background-color:;" class="col-orange-bg" |
| style="background-color:;" class="col-orange-bg" |
| style="background-color:;" class="col-orange-bg" |
| style="background-color:;" class="col-orange-bg" |
| style="background-color:;" class="col-orange-bg" |
| style="background-color:;" class="col-orange-bg" |
| style="background-color:;" class="col-orange-bg" |
| style="background-color:;" class="col-orange-bg" |
| style="background-color:;" class="col-orange-bg" |
| style="background-color:;" class="col-orange-bg" |
|-
|'''library'''
|
|
|
|
|
|
|
|
| style="background-color:;" class="col-orange-bg" |
|
| style="background-color:;" class="col-orange-bg" |
|}

===="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 [[ShareVDEmembers:APIdoc/RESTFul API/Search API#Stats|/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.

====[[ShareVDEmembers:APIdoc/RESTFul API|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:"<nowiki>https://svde.org/languages/ita</nowiki>"

'''Example #8: works having one or another language'''

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

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

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

====[[ShareDoc:GraphQL API|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:\"<nowiki>https://svde.org/languages/ita</nowiki>\""]

'''Example #8: works having one or another language'''

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

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

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

{{DEFAULTSORT:Share-VDE APIs}}
<references />

2023-12-21T10:09:59Z

Andrea Gazzarini:

The following link: https://www.getpostman.com/collections/bd55c075725e90383779 points to a collection of API examples that can be imported in PostMan<ref><nowiki>https://www.postman.com</nowiki></ref> using the steps described below.

The examples you'll find in the collection target the SIT environment described [[ShareVDEmembers:Environments|here]].

====Install Postman / access Postman web application====
Postman is available in several shapes: as a standalone or web application. The interface is pretty similar in both shapes.

You should

*install the application in your machine (not needed if you prefer the web application)
*create an account
*login

====Create a workspace====
The very first time you log into the application you should create a new workspace. That can be done using the "Workspace" menu item. The workspace can be a team or personal workspace.

Although it is possible to create also a "public" workspace, at this stage we don't recommend to create that for hosting the Share VDE API calls.
====Import the sample collection====
Once the workspace has been created click on the "Import" link that appears on the top of the explorer panel[[File:Postman "Import" menu item .png|none|thumb|551x551px|link=https://wiki.share-vde.org/wiki/File:Postman_%22Import%22_menu_item_.png]]The import dialog should appear. You need to select the "Links" tab and put this link https://api.postman.com/collections/18463300-129f4856-9257-4b16-85bf-7b4920af482f?access_key=PMAT-01HJ5XM822ZT5CBC29YTYC6S1Z in the text box, as illustrated in the following picture.[[File:import.png|none|thumb|753x753px|link=https://wiki.share-vde.org/wiki/File:import.png]]Once confirmed, in the left explorer pane you should see the examples. Just click on one of them and it executes the request, including the authentication workflow.[[File:collection imported.png|none|thumb|745x745px|link=https://wiki.share-vde.org/wiki/File:collection_imported.png]]
====Collection overview====
The examples have been divided in several subfolders, listed and described as follows.

=====REST=====
The folder contains the examples related to the REST API.

======Content Negotiation======
The content negotiation capabilities, as described [[ShareVDEmembers:TechnicalDocumentation/Content Negotiation|in this page]]. Note there are three sub-folders that illustrate the three different ways to negotiate / request a given format.

======Provenance API======
ShareVDE entities are the result of merging data coming from several sources. As a consequence of that, an entity provides a set of attributes that have been originally contributed by one or more sources. We call those sources "provenances".

By means of the Provenance API, the requestor can list the provenances that contributed to a given entity.

======Core Entities (e.g. Opus, Work, Instance)======
There is a folder for each type of entity managed in ShareVDE. API calls have been divided by entity for simplifying and better organising them.

======Varia======

*OpenAPI Specs: the request produces a JSON that can be imported in tools like https://editor.swagger.io/

=====GraphQL=====
The folder contains the examples related to the GraphQL API. Each folder includes specific entities; in addition there are two requests that can be used as templates:

*'''Sample Query Template''': a query example with variables
*'''Sample Schema Request''': a schema query example
<references />
__FORCETOC__