ShareDoc:GraphQL API - Revision history

Massimiliano Branca at 12:48, 3 July 2026

2026-07-03T12:48:46Z

@@ Line 55: / Line 55: @@
+}
 </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.
 '''Query vs. mutation behaviour.''' The difference matters for a read-only integrator:
@@ Line 713: / Line 712: @@
 ====publications====
 Retrieves the list of Publications a given person contributed to.
 ===<span class="mw-headline ve-pasteProtect" id="Agent" style="box-sizing: inherit;" data-ve-attributes="{&quot;style&quot;:&quot;box-sizing: inherit;&quot;}">Meeting</span>===
 Gathering of individuals or representatives of various bodies for the purpose of discussing and/or acting on topics of common interest. It is a concrete subclass of Agent and provides a set of attributes, both datatype and object property which interconnect the entity to opuses and other bibliographic entities in the Share-VDE domain model.
@@ Line 864: / Line 819: @@
 |0...1
 |N.A.
 |}
 ===Organisation ===

Massimiliano Branca at 12:47, 3 July 2026

2026-07-03T12:47:49Z

Show changes

Massimiliano Branca at 12:45, 3 July 2026

2026-07-03T12:45:40Z

← Older revision		Revision as of 12:45, 3 July 2026
Line 381:		Line 381:
	**'''USER_DEFINED''': in case of simple search where at least one query term is prefixed by a mandatory (+) or unwanted (-) modifier.		**'''USER_DEFINED''': in case of simple search where at least one query term is prefixed by a mandatory (+) or unwanted (-) modifier.

	===~~organisation~~===		===organization===
	Retrieves the ~~organisation~~ associated with a URI.		Retrieves the organization associated with a URI.

	<br />'''Request & Response'''		<br />'''Request & Response'''

	The request accepts a single parameter which is the Share-VDE URI of the ~~organisation~~ we are looking for.		The request accepts a single parameter which is the Share-VDE URI of the organization we are looking for.
	{\| class="wikitable"		{\| class="wikitable"
	\|+Input Parameters		\|+Input Parameters
Line 396:		Line 396:
	\|uri		\|uri
	\|Share-VDE URI		\|Share-VDE URI
	\|The Share-VDE URI associated with the ~~organisation~~ we want to retrieve		\|The Share-VDE URI associated with the organization we want to retrieve
	\|1		\|1
	\|}		\|}
	The response is the ~~organisation~~ associated with the input URI, if that exists. The exact ~~organisation~~ representation, in terms of attributes, depends on the request shape (i.e. the attributes that have been indicated in the request).		The response is the organization associated with the input URI, if that exists. The exact organization representation, in terms of attributes, depends on the request shape (i.e. the attributes that have been indicated in the request).
	===families===		===families===
	Search across all families using one available query language. Input parameters are the same we already described in the [[ShareVDEmembers:APIdoc/GraphQL API#agents\|Agent section]] and also the response includes the same sections already described for the agents. Differences are:		Search across all families using one available query language. Input parameters are the same we already described in the [[ShareVDEmembers:APIdoc/GraphQL API#agents\|Agent section]] and also the response includes the same sections already described for the agents. Differences are:

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