ShareDoc:API documentation - Revision history

Serena Cericola at 08:40, 28 May 2024

2024-05-28T08:40:15Z

← Older revision		Revision as of 08:40, 28 May 2024
Line 1:		Line 1:
	== Introduction ==		== Introduction ==
	{{DISPLAYTITLE:Share-VDE APIs}}		{{DISPLAYTITLE:Share-VDE APIs: cross-cutting concepts}}

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

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

Serena Cericola at 07:57, 21 February 2024

2024-02-21T07:57:21Z

← Older revision		Revision as of 07:57, 21 February 2024
Line 28:		Line 28:

	==Common Concepts==		==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 [[ShareDoc:RESTFul API\|REST]]).		Before going ahead with the API description, it's important to consolidate some concepts that are shared between the two available interfaces ([[ShareDoc:GraphQL API\|GraphQL]] and [[ShareDoc:RESTFul API\|REST]]).

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

	*[[ShareDoc:Content Negotiation\|Content Negotiation]]: Share-VDE resources are available in several formats, learn how to deal with the different representations		*[[ShareDoc:Content Negotiation\|Content Negotiation]]: Share-VDE resources are available in several formats, learn how to deal with the different representations.
	*[[ShareDoc:Query Languages\|Query Languages]]: there are multiple query languages available in Share-VDE. This section offers a detailed explanation about them.		*[[ShareDoc: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.		The remaining part of this page describes additional details you should be aware before interacting with the API.

	===Pagination===		===Pagination===

Serena Cericola at 08:53, 20 February 2024

2024-02-20T08:53:18Z

← Older revision		Revision as of 08:53, 20 February 2024
Line 7:		Line 7:
	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.		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]].		We strongly recommend to experiment the Share-VDE API using the [[ShareDoc: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:		This page offers a high-level overview of the Share-VDE public API, which are detailed in the following two sections:

Serena Cericola at 15:59, 16 February 2024

2024-02-16T15:59:38Z

← Older revision		Revision as of 15:59, 16 February 2024
Line 491:		Line 491:
	!'''Default Value'''		!'''Default Value'''
	\|-		\|-
	\|filters ([[ShareDoc:GraphQL API\|GraphQL]]) / filter ([[~~ShareVDEmembers~~:~~APIdoc/~~RESTFul API\|REST]])		\|filters ([[ShareDoc:GraphQL API\|GraphQL]]) / filter ([[ShareDoc:RESTFul API\|REST]])
	\|String		\|String
	\|A valid filter clause (see below)		\|A valid filter clause (see below)
Line 1,056:		Line 1,056:
	**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.		**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====		====[[ShareDoc:RESTFul API\|REST]] Examples====
	'''Example #1: publications having 1982 as year'''		'''Example #1: publications having 1982 as year'''

Serena Cericola at 15:57, 16 February 2024

2024-02-16T15:57:39Z

← Older revision		Revision as of 15:57, 16 February 2024
Line 30:		Line 30:
	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 [[ShareDoc:RESTFul API\|REST]]).		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 [[ShareDoc:RESTFul API\|REST]]).

	*[[~~ShareVDEmembers~~:Simple Search\|Simple Search:]] How the simple search works in Share-VDE, concepts and common behaviours		*[[ShareDoc: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		*[[ShareDoc: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.		*[[ShareDoc: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.		The remaining part of this page describes other common things you should be aware before interacting with the API.

Serena Cericola at 13:33, 16 February 2024

2024-02-16T13:33:34Z

Show changes

Andrea Gazzarini at 20:02, 22 December 2023

2023-12-22T20:02:10Z

← Older revision		Revision as of 20:02, 22 December 2023
Line 19:		Line 19:
	This page offers a high-level overview of the Share-VDE public API, which are detailed in the following two sections:		This page offers a high-level overview of the Share-VDE public API, which are detailed in the following two sections:

	*[[~~ShareVDEmembers~~:~~APIdoc/~~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.		*[[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.		*[[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.

Line 39:		Line 39:

	==Common Concepts==		==Common Concepts==
	Before going ahead with the API description, it's important to centralise some concepts that are shared between the two available interfaces ([[~~ShareVDEmembers~~:~~APIdoc/~~GraphQL API\|GraphQL]] and [[ShareVDEmembers:APIdoc/RESTFul API\|REST]]).		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:Simple Search\|Simple Search:]] How the simple search works in Share-VDE, concepts and common behaviours
Line 493:		Line 493:
	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:		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 [[~~ShareVDEmembers~~:~~APIdoc/~~GraphQL API\|GraphQL]] API the parameter is called '''filters''' and it is an array of strings		*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'''		* in [[ShareVDEmembers:APIdoc/RESTFul API\|RESTful]] API the parameter is a repeatable request parameter called '''filter'''

Line 502:		Line 502:
	!'''Default Value'''		!'''Default Value'''
	\|-		\|-
	\|filters ([[~~ShareVDEmembers~~:~~APIdoc/~~GraphQL API\|GraphQL]]) / filter ([[ShareVDEmembers:APIdoc/RESTFul API\|REST]])		\|filters ([[ShareDoc:GraphQL API\|GraphQL]]) / filter ([[ShareVDEmembers:APIdoc/RESTFul API\|REST]])
	\|String		\|String
	\|A valid filter clause (see below)		\|A valid filter clause (see below)
Line 1,104:		Line 1,104:
	filter=publicationYear:1982&filter=language:"<nowiki>https://svde.org/places/28372837</nowiki>"		filter=publicationYear:1982&filter=language:"<nowiki>https://svde.org/places/28372837</nowiki>"

	====[[~~ShareVDEmembers~~:~~APIdoc/~~GraphQL API\|GraphQL]] Examples====		====[[ShareDoc:GraphQL API\|GraphQL]] Examples====
	'''Example #1: publications having 1982 as year'''		'''Example #1: publications having 1982 as year'''

Andrea Gazzarini at 19:59, 22 December 2023

2023-12-22T19:59:07Z

← Older revision		Revision as of 19:59, 22 December 2023
Line 1:		Line 1:



Line 28:		Line 29:
	*'''"functional"''' those entities that are part of the Share-VDE Core Domain Model (e.g. Agents, Opuses, Works, Instances, Items)		*'''"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).		*'''"technical"''' those entities required by some '''technical constraint''' in order to enrich the core entities with additional information (e.g. Collections, Facets, Pagination metadata).

Andrea Gazzarini at 19:57, 22 December 2023

2023-12-22T19:57:32Z

← Older revision		Revision as of 19:57, 22 December 2023
Line 27:		Line 27:

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

Andrea Gazzarini at 19:57, 22 December 2023

2023-12-22T19:57:14Z

← Older revision		Revision as of 19:57, 22 December 2023
Line 1:		Line 1:




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

	* [[ShareVDEmembers:APIdoc/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/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.		*[[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)==		==Domain model (diagram)==
Line 27:		Line 29:
	*'''"technical"''' those entities required by some '''technical constraint''' in order to enrich the core entities with additional information (e.g. Collections, Facets, Pagination metadata)		*'''"technical"''' those entities required by some '''technical constraint''' in order to enrich the core entities with additional information (e.g. Collections, Facets, Pagination metadata)

	~~<span><br /></span>~~

	~~<br />~~


	==Common Concepts==		==Common Concepts==
	Before going ahead with the API description, it's important to centralise some concepts that are shared between the two available interfaces ([[ShareVDEmembers:APIdoc/GraphQL API\|GraphQL]] and [[ShareVDEmembers:APIdoc/RESTFul API\|REST]]).		Before going ahead with the API description, it's important to centralise some concepts that are shared between the two available interfaces ([[ShareVDEmembers:APIdoc/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: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: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.		*[[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.		The remaining part of this page describes other common things you should be aware before interacting with the API.
Line 57:		Line 59:
	\|Integer		\|Integer
	\|The offset of the first item returned in results.		\|The offset of the first item returned in results.
	\|0		\| 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">		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">
Line 71:		Line 73:
	}		}
	</syntaxhighlight>		</syntaxhighlight>
	===Sort===		=== Sort===
	All operations that return in response a collection of entities accept an optional parameter that allow to sort the (paged) results.		All operations that return in response a collection of entities accept an optional parameter that allow to sort the (paged) results.
	{\| class="wikitable" style=""		{\| class="wikitable" style=""
Line 81:		Line 83:
	\|sort		\|sort
	\|String		\|String
	\|The sort clause (see below)		\| The sort clause (see below)
	\| -----		\| -----
	\|}		\|}
Line 487:		Line 489:

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

	{\| class="wikitable" style=""		{\| class="wikitable" style=""
Line 498:		Line 500:
	\|String		\|String
	\|A valid filter clause (see below)		\|A valid filter clause (see below)
	\| -----		\| -----
	\|}A filter clause is composed by 2 parts:		\|}A filter clause is composed by 2 parts:

Line 510:		Line 512:

	*'''multiple clause''' can be specified in '''one filter''': in that case		*'''multiple clause''' can be specified in '''one filter''': in that case
	**they must refer to the same attribute		** they must refer to the same attribute
	**they must be separated using the '''OR''' keyword		**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)		**the attribute (and the colon) '''must repeated for each value''' (e.g. year:1982 OR year:2020 OR year:1999)
Line 1,052:		Line 1,054:
	\|}		\|}

	==== "library" and "provenance" filters ====		===="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'''.		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.		*'''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		*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 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.		**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====		====[[ShareVDEmembers:APIdoc/RESTFul API\|REST]] Examples====

← Older revision		Revision as of 15:57, 16 February 2024
Line 30:		Line 30:
	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 [[ShareDoc:RESTFul API\|REST]]).		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 [[ShareDoc:RESTFul API\|REST]]).

	*[[~~ShareVDEmembers~~:Simple Search\|Simple Search:]] How the simple search works in Share-VDE, concepts and common behaviours		*[[ShareDoc: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		*[[ShareDoc: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.		*[[ShareDoc: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.		The remaining part of this page describes other common things you should be aware before interacting with the API.