ShareDoc:GraphQL API - Revision history

Serena Cericola at 08:52, 28 May 2024

2024-05-28T08:52:20Z

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

	==Introduction==		==Introduction==
	The Share-VDE Domain Model can be queried using GraphQL.		The Share-VDE Domain Model can be queried using GraphQL.

Serena Cericola at 13:28, 19 February 2024

2024-02-19T13:28:24Z

Andrea Gazzarini at 09:02, 8 February 2024

2024-02-08T09:02:04Z

← Older revision		Revision as of 09:02, 8 February 2024
Line 53:		Line 53:
	}		}
	</syntaxhighlight>In the example, the status field is accessible only if the requestor has a svde-editor-base (or higher) role associated. Otherwise it will return null.		</syntaxhighlight>In the example, the status field is accessible only if the requestor has a svde-editor-base (or higher) role associated. Otherwise it will return null.

	~~==Print/Online publication grouping==~~
	~~A special flag on publications entities which allow to group them by print/online formats.~~

	~~[[ShareVDEmembers:APIdoc/GraphQL API/Print-Online Publication Grouping\|See the feature description here]].~~
	==Top Level Queries==		==Top Level Queries==

Line 96:		Line 91:
	\|String		\|String
	\|One of the following values<br />		\|One of the following values<br />

	*AGENT		*AGENT
	*INSTANCE (used for publications)		*INSTANCE (used for publications)
	*OPUS		*OPUS
	*ITEM		*ITEM



Line 137:		Line 132:
	===Simple search===		===Simple search===
	Simple search uses a basic query approach. That means the query is supposed to contains only terms (and optionally modifiers).		Simple search uses a basic query approach. That means the query is supposed to contains only terms (and optionally modifiers).


	'''Request & Response'''		'''Request & Response'''
Line 625:		Line 619:
	*Format		*Format

	Apart attributes that are specific to a given entity type (e.g. a Place could have a "coordinates" attribute) the whole group shares the following structure:[[File:1623235578601.png\|none\|thumb~~\|link=https://wiki.share-vde.org/wiki/File:1623235578601.png~~]]		Apart attributes that are specific to a given entity type (e.g. a Place could have a "coordinates" attribute) the whole group shares the following structure:[[File:1623235578601.png\|none\|thumb]]
	==Core Entities==		==Core Entities==
	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 state and operations.		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 state and operations.
Line 1,744:		Line 1,738:
	}		}
	</syntaxhighlight>		</syntaxhighlight>


	<nowiki>------</nowiki>		<nowiki>------</nowiki>
	<references />		<references />

Andrea Gazzarini at 09:01, 8 February 2024

2024-02-08T09:01:27Z

Show changes

Andrea Gazzarini: Created page with "==Introduction== The Share-VDE Domain Model can be queried using GraphQL. This page describes the interface in terms of entities, operations, parameters and information rel..."

2023-12-22T20:00:23Z

Created page with "==Introduction== The Share-VDE Domain Model can be queried using GraphQL. This page describes the interface in terms of entities, operations, parameters and information rel..."

New page

==Introduction==
The Share-VDE Domain Model can be queried using GraphQL.

This page describes the interface in terms of entities, operations, parameters and information related with this interaction mode.
==Schema==
GraphQL is a schema-based contract interface. That means a domain using GraphQL as interaction protocol must declare a schema where the following things need to be defined:

*entities
*attributes
*operations
*parameters

A special set of constructs within the protocol/language allow clients to query and introspect the defined schema. Here's an example <syntaxhighlight lang="json">
{
__schema {
types {
name
}
}
}
</syntaxhighlight>which produces the following response (partial):<syntaxhighlight lang="json">

"data": {
"__schema": {
"types": [
{
"name": "Agent"
},
{
"name": "AgentClause"
},
{
"name": "AgentCollection"
},
{
"name": "AgentStructQL"
},
...
</syntaxhighlight>More information about the GraphQL introspection capability can be found here; also please keep note the Share-VDE GraphiQL UI provides a navigable section which queries the schema and provides the introspection data in a human-readable way (see the ''Docs'' link on the right side of the UI).
==Directives==
At time of writing there's only one directive in the Share-VDE GraphQL Schema: it is called "availableOnlyFor" and it is used to mark protected resources that require a privileged role for their access.

See the following schema extract:<syntaxhighlight>
{
type Provenance {
uri: ID!

code: String

description: String

status: [RuntimeClusterStatus] @availableOnlyFor(role: "svde-editor-base")
}
</syntaxhighlight>In the example, the status field is accessible only if the requestor has a svde-editor-base (or higher) role associated. Otherwise it will return null.

== [[ShareVDEmembers:APIdoc/GraphQL API/Provenance|Provenances]] ==
Being a cross-cutting concept, the Provenance API and their behaviour are detailed in [[ShareVDEmembers:APIdoc/GraphQL API/Provenance|this top-level section]], beside the other available API.

==<span class="mw-headline" id="Search_API" style="box-sizing: inherit;">[[ShareVDEmembers:APIdoc/GraphQL API/Search API|Search API]]</span>==
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/GraphQL API/Search API|The available endpoints are detailed in this page]].

==<span class="mw-headline" id="Curation_API" style="box-sizing: inherit;">[[ShareVDEmembers:APIdoc/GraphQL API/Curation API|Curation API]]</span>==
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/GraphQL API/Curation API|The available endpoints are detailed in this page]].

← Older revision		Revision as of 13:28, 19 February 2024
Line 231:		Line 231:
	A response provides the '''following sections''':		A response provides the '''following sections''':

	*'''resources''': a sublist of the matching agents according with the '''[[~~ShareVDEmembers~~:~~APIdoc~~#Pagination\|pagination]]''' parameters in the request. Each agent in the resources list is represented using the attribute indicated in the request (if they are not null). Note that an agent can have datatype and/or object properties, with different cardinalities. That means a representation is not only composed by datatype (literal) attributes but could also involve other entities (e.g. opuses belonging to an agent)		*'''resources''': a sublist of the matching agents according with the '''[[ShareDoc:API documentation#Pagination\|pagination]]''' parameters in the request. Each agent in the resources list is represented using the attribute indicated in the request (if they are not null). Note that an agent can have datatype and/or object properties, with different cardinalities. That means a representation is not only composed by datatype (literal) attributes but could also involve other entities (e.g. opuses belonging to an agent)
	*'''facets'''		*'''facets'''
	**'''beginningDate''': virtual attribute with a different meaning depending on the agent type (e.g. startDate for families, birthDate for people)		**'''beginningDate''': virtual attribute with a different meaning depending on the agent type (e.g. startDate for families, birthDate for people)
	**'''endingDate''': virtual attribute with a different meaning depending on the agent type (e.g. endDate for families, deathDate for people)		**'''endingDate''': virtual attribute with a different meaning depending on the agent type (e.g. endDate for families, deathDate for people)
	**'''location''': virtual attribute with a different meaning depending on the agent type (e.g. birth or death place for people)		**'''location''': virtual attribute with a different meaning depending on the agent type (e.g. birth or death place for people)
	*'''[[~~ShareVDEmembers~~:~~APIdoc~~#Pagination\|pagination]]'''		*'''[[ShareDoc:API documentation#Pagination\|pagination]]'''
	*'''matchMode''': <span class="ve-pasteProtect" style="color: rgb(51, 51, 51)" data-ve-attributes="{"style":"color: rgb(51, 51, 51)"}">informs the caller about the query logic that has been executed</span>. Possible values are		*'''matchMode''': <span class="ve-pasteProtect" style="color: rgb(51, 51, 51)" data-ve-attributes="{"style":"color: rgb(51, 51, 51)"}">informs the caller about the query logic that has been executed</span>. Possible values are
	**'''FULL''': it indicates that an AND logic between query terms has been applied		**'''FULL''': it indicates that an AND logic between query terms has been applied
Line 338:		Line 338:
	**'''year''': the meeting year (that is not the full date)		**'''year''': the meeting year (that is not the full date)
	**'''location''': entities of type Place. For each bucket we can ask the URI, the label and the count		**'''location''': entities of type Place. For each bucket we can ask the URI, the label and the count
	*'''[[~~ShareVDEmembers~~:~~APIdoc~~#Pagination\|pagination]]'''		*'''[[ShareDoc:API documentation#Pagination\|pagination]]'''
	*'''matchMode''': <span class="ve-pasteProtect" style="color: rgb(51, 51, 51)" data-ve-attributes="{"style":"color: rgb(51, 51, 51)"}">informs the caller about the query logic that has been executed</span>. Possible values are		*'''matchMode''': <span class="ve-pasteProtect" style="color: rgb(51, 51, 51)" data-ve-attributes="{"style":"color: rgb(51, 51, 51)"}">informs the caller about the query logic that has been executed</span>. Possible values are
	**'''FULL''': it indicates that an AND logic between query terms has been applied		**'''FULL''': it indicates that an AND logic between query terms has been applied
Line 372:		Line 372:
	**'''dissolutionYear''': the year (not the full date) an organisation has been dissolved		**'''dissolutionYear''': the year (not the full date) an organisation has been dissolved
	**'''location''': entities of type Place. For each bucket we can ask the URI, the label and the count		**'''location''': entities of type Place. For each bucket we can ask the URI, the label and the count
	*'''[[~~ShareVDEmembers~~:~~APIdoc~~#Pagination\|pagination]]'''		*'''[[ShareDoc:API documentation#Pagination\|pagination]]'''
	*'''matchMode''': <span class="ve-pasteProtect" style="color: rgb(51, 51, 51)" data-ve-attributes="{"style":"color: rgb(51, 51, 51)"}">informs the caller about the query logic that has been executed</span>. Possible values are		*'''matchMode''': <span class="ve-pasteProtect" style="color: rgb(51, 51, 51)" data-ve-attributes="{"style":"color: rgb(51, 51, 51)"}">informs the caller about the query logic that has been executed</span>. Possible values are
	**'''FULL''': it indicates that an AND logic between query terms has been applied		**'''FULL''': it indicates that an AND logic between query terms has been applied
Line 405:		Line 405:
	**'''endDate''': the year (not the full date) a family appeared		**'''endDate''': the year (not the full date) a family appeared
	**'''startDate''': the year (not the full date) a family disappeared		**'''startDate''': the year (not the full date) a family disappeared
	*'''[[~~ShareVDEmembers~~:~~APIdoc~~#Pagination\|pagination]]'''		*'''[[ShareDoc:API documentation#Pagination\|pagination]]'''
	*'''matchMode''': <span class="ve-pasteProtect" style="color: rgb(51, 51, 51)" data-ve-attributes="{"style":"color: rgb(51, 51, 51)"}">informs the caller about the query logic that has been executed</span>. Possible values are		*'''matchMode''': <span class="ve-pasteProtect" style="color: rgb(51, 51, 51)" data-ve-attributes="{"style":"color: rgb(51, 51, 51)"}">informs the caller about the query logic that has been executed</span>. Possible values are
	**'''FULL''': it indicates that an AND logic between query terms has been applied		**'''FULL''': it indicates that an AND logic between query terms has been applied
Line 453:		Line 453:
	The response provides 3 sections:		The response provides 3 sections:

	*'''resources''': a sublist of the matching opuses according with the '''[[~~ShareVDEmembers~~:~~APIdoc~~#Pagination\|pagination]]''' parameters in the request. Each entity in the resources list is represented using the attribute specified in the request (if they are not null).		*'''resources''': a sublist of the matching opuses according with the '''[[ShareDoc:API documentation#Pagination\|pagination]]''' parameters in the request. Each entity in the resources list is represented using the attribute specified in the request (if they are not null).
	*'''facets'''		*'''facets'''
	**'''contributor''': contributors (as URIs) associated with the opuses in results		**'''contributor''': contributors (as URIs) associated with the opuses in results
Line 459:		Line 459:
	**'''format''': the formats (as URIs) of the publication indirectly associated with the opuses in results		**'''format''': the formats (as URIs) of the publication indirectly associated with the opuses in results
	**'''genre''': the genres (as URIs) associated with the opuses in results		**'''genre''': the genres (as URIs) associated with the opuses in results
	*'''[[~~ShareVDEmembers~~:~~APIdoc~~#Pagination\|pagination]]'''		*'''[[ShareDoc:API documentation#Pagination\|pagination]]'''
	*'''matchMode''': <span class="ve-pasteProtect" style="color: rgb(51, 51, 51)" data-ve-attributes="{"style":"color: rgb(51, 51, 51)"}">informs the caller about the query logic that has been executed</span>. Possible values are		*'''matchMode''': <span class="ve-pasteProtect" style="color: rgb(51, 51, 51)" data-ve-attributes="{"style":"color: rgb(51, 51, 51)"}">informs the caller about the query logic that has been executed</span>. Possible values are
	**'''FULL''': it indicates that an AND logic between query terms has been applied		**'''FULL''': it indicates that an AND logic between query terms has been applied
Line 581:		Line 581:
	**'''format''': the formats (as URIs) of the publication indirectly associated with the opuses in results		**'''format''': the formats (as URIs) of the publication indirectly associated with the opuses in results
	**'''publicationYear''': the (instance) publication year		**'''publicationYear''': the (instance) publication year
	*'''[[~~ShareVDEmembers~~:~~APIdoc~~#Pagination\|pagination]]'''		*'''[[ShareDoc:API documentation#Pagination\|pagination]]'''

	===publication===		===publication===