ShareDoc:RESTFul API - Revision history

Serena Cericola at 08:46, 28 May 2024

2024-05-28T08:46:04Z

← Older revision		Revision as of 08:46, 28 May 2024
Line 1:		Line 1:
	{{DISPLAYTITLE:Share-VDE: RESTful API}}		{{DISPLAYTITLE:Share-VDE RESTful API}}

	==Introduction==		==Introduction==

Serena Cericola at 08:45, 28 May 2024

2024-05-28T08:45:45Z

← Older revision		Revision as of 08:45, 28 May 2024
Line 1:		Line 1:
	{{DISPLAYTITLE:RESTful API}}		{{DISPLAYTITLE:Share-VDE: RESTful API}}

	==Introduction==		==Introduction==

Serena Cericola at 15:25, 20 February 2024

2024-02-20T15:25:39Z

← Older revision		Revision as of 15:25, 20 February 2024
Line 494:		Line 494:
	*'''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)		*'''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)

	===[[~~ShareVDEmembers~~:~~APIdoc/RESTFul API/~~Search API\|Search API]]===		===[[ShareDoc:Search API\|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''').		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''').

	[[~~ShareVDEmembers~~:~~APIdoc/RESTFul API/~~Search API\|The available endpoints are detailed in this page]].<br />		[[ShareDoc:Search API\|The available endpoints are detailed in this page]].<br />
	__FORCETOC__		__FORCETOC__

Andrea Gazzarini at 14:31, 20 February 2024

2024-02-20T14:31:50Z

Show changes

Andrea Gazzarini at 14:29, 20 February 2024

2024-02-20T14:29:42Z

← Older revision		Revision as of 14:29, 20 February 2024
Line 497:		Line 497:
	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''').		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''').

	[[ShareVDEmembers:APIdoc/RESTFul API/Search ~~API\|The available endpoints are detailed in this page]].~~		[[ShareVDEmembers:APIdoc/RESTFul API/Search API\|The available endpoints are detailed in this page]].<br />

	~~===[[ShareVDEmembers:APIdoc/RESTFul API/Curation API\|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)

	~~[[ShareVDEmembers:APIdoc/RESTFul API/Curation~~ API\|The available endpoints are detailed in this page]].<br />
	__FORCETOC__		__FORCETOC__

Serena Cericola at 13:20, 19 February 2024

2024-02-19T13:20:10Z

← Older revision		Revision as of 13:20, 19 February 2024
Line 435:		Line 435:
	#obtain the single source record using its local ID as the URI.		#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 [[~~ShareVDEmembers~~:~~TechnicalDocumentation/~~Content Negotiation\|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.		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 [[ShareDoc:Content Negotiation\|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:		The shortlist can be obtained adding to the entity's /records URI segment the full=false parameter, just like in this example:

Andrea Gazzarini: Created page with "{{DISPLAYTITLE:RESTful API}} ==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 ca..."

2024-02-08T09:12:25Z

Created page with "{{DISPLAYTITLE:RESTful API}} ==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 ca..."

New page

{{DISPLAYTITLE:RESTful API}}

==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. <nowiki>https://svde.org/agents/201</nowiki>)

==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 [https://sit2-base-svde.atcult.it/people/201.json 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): <syntaxhighlight lang="json">
"_links": {
...
"opuses": [
{
"href": "https://svde.org/agents/201/opuses"
},
{
"href": "https://svde.org/people/201/opuses"
}
],
...
</syntaxhighlight>which would lead to the [https://sit2-base-svde.atcult.it/agents/201/opuses.json list of opuses]. There, each returned opus provides a set of outgoing links, including works, contributors, genre:<syntaxhighlight lang="json">
"_links": {
...
"genre": {
"href": "https://svde.org/genres/gf2015026020"
},
"contributors": {
"href": "https://svde.org/opuses/401/contributors"
},
"works": {
"href": "https://svde.org/opuses/401/works"
}

}
</syntaxhighlight>

==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: <syntaxhighlight lang="json">
{
"_embedded": {
"resourceList": [
... (paged resource list)
]
},
...
"meta": {
"matchMode": "FULL"
}
}
</syntaxhighlight>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:

#Simple search using one or more terms (e.g. history republic 1972)
#Query response including entities E1, E2, E3
#(on demand) Explain for E1
#(on demand) Explain for E2
#(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
<syntaxhighlight lang="json">
/organisations/101/explanation?terms=american%20library

{
"meta": {
"aut": {
"label": "author",
"language": "eng",
"type": "Role"
}
},
"aut": [
{
"title": "Library media & information skills"
},
{
"titleAlternative": "Library media and information skills"
}
],
"name": "American Library Association",
...
}
</syntaxhighlight>

*in case the language is available it is included beside the value
<syntaxhighlight lang="json">
/people/201/explanation?terms=daresbury

{
"birthPlace": {
"label": {
"value": "Daresbury",
"language": "eng"
}
},
...
}
</syntaxhighlight>

*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)
<syntaxhighlight lang="json">
/opuses/411/explanation?terms=georgia%20press

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

=====Examples=====

======Agents======
[https://sit2-base-svde.atcult.it/agents/201/explanation?terms=carroll%201832 Example #1: Agent explanation: name and birth date]

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

[https://sit2-base-svde.atcult.it/agents/201/explanation?terms=Daresbury 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)

[https://sit2-base-svde.atcult.it/agents/207/explanation?terms=Washington%20City 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)

[https://sit2-base-svde.atcult.it/agents/207/explanation?terms=Washington%20AND%20City 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)

[https://sit2-base-svde.atcult.it/agents/207/explanation?terms="Washington%20City" Example #5: Agent explanation: english alternative form of birth place (phrase query)]

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

[https://sit2-base-svde.atcult.it/agents/202/explanation?terms=Rome Example #6: Agent explanation: english preferred form of death place]

[https://sit2-base-svde.atcult.it/agents/202/explanation?terms=urbs Example #7: Agent explanation: latin preferred form of death place]

[https://sit2-base-svde.atcult.it/agents/207/explanation?terms=writer Example #8: Agent explanation: english preferred form of occupation]

[https://sit2-base-svde.atcult.it/agents/207/explanation?terms=scrittore Example #9: Agent explanation: italian preferred form of occupation]

[https://sit2-base-svde.atcult.it/agents/245/explanation?terms=News%20analysts Example #10: Agent explanation: english alternative form of occupation]

[https://sit2-base-svde.atcult.it/agents/201/explanation?terms=alice%20wonderland%20looking%20glass Example #11: Agent explanation: related Opus (headings) and agent role (author).]

======People======
[https://sit2-base-svde.atcult.it/people/201/explanation?terms=carroll%201832 Example #1: Person explanation: name and birth date]

[https://sit2-base-svde.atcult.it/people/201/explanation?terms=Daresbury Example #2: Person explanation: english preferred form of birth place]

[https://sit2-base-svde.atcult.it/people/207/explanation?terms=Washington%20City Example #3: Person explanation: english preferred and alternative form of birth place]

[https://sit2-base-svde.atcult.it/people/207/explanation?terms="Washington%20City" Example #4: Person explanation: english alternative form of birth place (phrase query)]

[https://sit2-base-svde.atcult.it/people/202/explanation?terms=Rome Example #5: Person explanation: english preferred form of death place]

[https://sit2-base-svde.atcult.it/people/202/explanation?terms=urbs Example #6: Person explanation: latin preferred form of death place]

[https://sit2-base-svde.atcult.it/people/207/explanation?terms=writer Example #7: Person explanation: english preferred form of occupation]

[https://sit2-base-svde.atcult.it/people/207/explanation?terms=scrittore Example #8: Person explanation: italian preferred form of occupation]

[https://sit2-base-svde.atcult.it/people/245/explanation?terms=News%20analysts Example #9: Person explanation: english alternative form of occupation]

======Organisations======
[https://sit2-base-svde.atcult.it/organisations/104/explanation?terms=Edimburgo Example #1: Organisation explanation: italian preferred form of location]

======Opuses======
[https://sit2-base-svde.atcult.it/opuses/401/explanation?terms=Novels Example #2: Opus explanation: english preferred form of genre]

[https://sit2-base-svde.atcult.it/opuses/401/explanation?terms=Regény Example #3: Opus explanation: Hungarian preferred form of genre]

[https://sit2-base-svde.atcult.it/opuses/402/explanation?terms=textbooks Example #4: Opus explanation: english alternative form of genre]

[https://sit2-base-svde.atcult.it/opuses/401/explanation?terms=luis%20carroll Example #5: Opus explanation: author name (in agent name and instance title)]

[https://sit2-base-svde.atcult.it/opuses/401/explanation?terms=Fantasy Example #6: Opus explanation: topical subject]

[https://sit2-base-svde.atcult.it/opuses/404/explanation?terms=Kennedy%20family Example #7: Opus explanation: name subject (the example includes also the author)]

[https://sit2-base-svde.atcult.it/opuses/401/explanation?terms=Cuthbert%20Vivian Example #8: Opus explanation: illustrator (work contributor) data]

[https://sit2-base-svde.atcult.it/opuses/401/explanation?terms=PR4611.A7%20I8%201978 Example #9: Opus explanation: (work) classification]

[https://sit2-base-svde.atcult.it/opuses/401/explanation?terms=1872 Example #10: Opus explanation: (instance) publication year]

[https://sit2-base-svde.atcult.it/opuses/402/explanation?terms=Chicago Example #11: Opus explanation: publication place]

[https://sit2-base-svde.atcult.it/opuses/411/explanation?terms=Georgia%20Press 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
<syntaxhighlight lang="json">
{
"preferredHeading": "Carroll, Lewis",
"alternateHeadings": [
"Karol, Luis",
"Dodgson, Charles Lutwìdge"
],
"birthDate": 1832,
"deathDate": 1898,
"_links": {
...
</syntaxhighlight>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:
<syntaxhighlight lang="json">
"_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"
}
],
</syntaxhighlight>
===Collection===
A list of resources with a predefined and relatively small size. The only example we have at the moment is the collection of [https://sit2-base-svde.atcult.it/people/201/occupations.json occupations] associated with a given person:<syntaxhighlight lang="json">
{
"_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://sit2-base-svde.atcult.it/people/201/occupations"
},
"Person": {
"href": "https://sit2-base-svde.atcult.it/people/201"
}
}
}
</syntaxhighlight>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 [[ShareVDEmembers:APIdoc#Pagination|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 [[ShareVDEmembers:Apidoc/RESTFul API#Resource|previously]]
*[[ShareVDEmembers:APIdoc#Pagination|pagination]] metadata: three attributes ('''totalMatches''', '''pageSize''' and '''startOffset''')
*facets: aggregations over the entity attributes. Facets depend on the type of the returned entities
<syntaxhighlight lang="json">
{
"_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
}
}
</syntaxhighlight>
===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:

#obtain the list of source records that contributed to form the entity's shape;
#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 [[ShareVDEmembers:TechnicalDocumentation/Content Negotiation|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:
<nowiki>https://svde.org/opuses/1234567890/records?full=false</nowiki>
The resulting shortlist will be:<syntaxhighlight lang="json">
{
"_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"
}
}
}
</syntaxhighlight>
==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)

===[[ShareVDEmembers:APIdoc/RESTFul API/Search API|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''').

[[ShareVDEmembers:APIdoc/RESTFul API/Search API|The available endpoints are detailed in this page]].

===[[ShareVDEmembers:APIdoc/RESTFul API/Curation API|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)

[[ShareVDEmembers:APIdoc/RESTFul API/Curation API|The available endpoints are detailed in this page]]. 
__FORCETOC__