ShareDoc:Content Negotiation - Revision history

Anna at 10:08, 22 September 2025

2025-09-22T10:08:12Z

← Older revision		Revision as of 10:08, 22 September 2025
Line 1:		Line 1:
	{{DISPLAYTITLE:Share-VDE REST API: Content Negotiation}}		{{DISPLAYTITLE:Share-VDE REST API: Content Negotiation}}

	C''~~ontent~~ negotiation'' is the mechanism used for serving different representations of a resource mapped to a given URI to help the user agent (i.e. the requestor) specify which "shape" is best suited for it.		''Content negotiation'' is the mechanism used for serving different representations of a resource mapped to a given URI to help the user agent (i.e. the requestor) specify which "shape" is best suited for it.

	When a client wants to obtain a Share-VDE resource, it requests it via a URL. The server uses this URL and the corresponding metadata to choose one of the available variants. Each "variant" is called a representation and it is associated to a given format. The following table lists the supported formats.		When a client wants to obtain a Share-VDE resource, it requests it via a URL. The server uses this URL and the corresponding metadata to choose one of the available variants. Each "variant" is called a representation and it is associated to a given format. The following table lists the supported formats.

Serena Cericola at 08:51, 28 May 2024

2024-05-28T08:51:26Z

← Older revision		Revision as of 08:51, 28 May 2024
Line 1:		Line 1:
			{{DISPLAYTITLE:Share-VDE REST API: Content Negotiation}}

	C''ontent negotiation'' is the mechanism used for serving different representations of a resource mapped to a given URI to help the user agent (i.e. the requestor) specify which "shape" is best suited for it.		C''ontent negotiation'' is the mechanism used for serving different representations of a resource mapped to a given URI to help the user agent (i.e. the requestor) specify which "shape" is best suited for it.

Serena Cericola at 08:50, 28 May 2024

2024-05-28T08:50:01Z

← Older revision		Revision as of 08:50, 28 May 2024
Line 43:		Line 43:
	\|}'''RIS and MARC formats only''': these media types are valid only at instance (e.g. /instances/I0003) or at bibliographic record level (e.g. /instances/I0003/records)		\|}'''RIS and MARC formats only''': these media types are valid only at instance (e.g. /instances/I0003) or at bibliographic record level (e.g. /instances/I0003/records)

	'''RDF formats only''': some RDF format return graphs instead of a triple sets. In ~~ShareVDE~~ the fourth dimension (the graph URI) is used for associating a triple to its provenance. As a consequence of that, if the request asks for a format which provides "triples" level info, it will get a "merged" view of the triples coming from all provenances, without any indication about the provenance itself.		'''RDF formats only''': some RDF format return graphs instead of a triple sets. In Share-VDE the fourth dimension (the graph URI) is used for associating a triple to its provenance. As a consequence of that, if the request asks for a format which provides "triples" level info, it will get a "merged" view of the triples coming from all provenances, without any indication about the provenance itself.

	In the example below, the requested format is n-triples: <syntaxhighlight>		In the example below, the requested format is n-triples: <syntaxhighlight>

Serena Cericola at 08:49, 28 May 2024

2024-05-28T08:49:23Z

← Older revision		Revision as of 08:49, 28 May 2024
Line 1:		Line 1:
	C''ontent negotiation'' is the mechanism used for serving different representations of a resource mapped to a given URI to help the user agent (i.e. the requestor) specify which "shape" is best suited for it.		C''ontent negotiation'' is the mechanism used for serving different representations of a resource mapped to a given URI to help the user agent (i.e. the requestor) specify which "shape" is best suited for it.

	When a client wants to obtain a Share VDE resource, it requests it via a URL. The server uses this URL and the corresponding metadata to choose one of the available variants.Each "variant" is called a representation and it is associated to a given format. The following table lists the supported formats.		When a client wants to obtain a Share-VDE resource, it requests it via a URL. The server uses this URL and the corresponding metadata to choose one of the available variants. Each "variant" is called a representation and it is associated to a given format. The following table lists the supported formats.
	{\| class="wikitable"		{\| class="wikitable"
	!'''Format'''		!'''Format'''

Andrea Gazzarini: Created page with "C''ontent negotiation'' is the mechanism used for serving different representations of a resource mapped to a given URI to help the user agent (i.e. the requestor) specify which "shape" is best suited for it. When a client wants to obtain a Share VDE resource, it requests it via a URL. The server uses this URL and the corresponding metadata to choose one of the available variants.Each "variant" is called a representation and it is associated to a given format. The follo..."

2024-02-08T09:09:35Z

Created page with "C''ontent negotiation'' is the mechanism used for serving different representations of a resource mapped to a given URI to help the user agent (i.e. the requestor) specify which "shape" is best suited for it. When a client wants to obtain a Share VDE resource, it requests it via a URL. The server uses this URL and the corresponding metadata to choose one of the available variants.Each "variant" is called a representation and it is associated to a given format. The follo..."

New page

C''ontent negotiation'' is the mechanism used for serving different representations of a resource mapped to a given URI to help the user agent (i.e. the requestor) specify which "shape" is best suited for it.

When a client wants to obtain a Share VDE resource, it requests it via a URL. The server uses this URL and the corresponding metadata to choose one of the available variants.Each "variant" is called a representation and it is associated to a given format. The following table lists the supported formats.
{| class="wikitable"
!'''Format'''
!'''Description'''
|-
|JSON
|https://en.wikipedia.org/wiki/HATEOAS
|-
|JSON-LD
|https://json-ld.org/
|-
|RDF XML
|https://www.w3.org/TR/rdf-syntax-grammar/
|-
|N-Triples
|https://www.w3.org/TR/n-triples/
|-
|N3
|https://www.w3.org/TeamSubmission/n3/
|-
|Turtle
|https://www.w3.org/TR/turtle/
|-
|N-Quads
|https://www.w3.org/TR/n-quads/
|-
|TriX
|https://en.wikipedia.org/wiki/TriX_(serialization_format)
|-
|TriG
|https://www.w3.org/TR/trig/
|-
|MARC
|https://en.wikipedia.org/wiki/MARC_standards#MARC_formats
|-
|MARCXML
|https://en.wikipedia.org/wiki/MARC_standards#MARCXML
|-
|RIS
|https://en.wikipedia.org/wiki/RIS_(file_format)
|}'''RIS and MARC formats only''': these media types are valid only at instance (e.g. /instances/I0003) or at bibliographic record level (e.g. /instances/I0003/records)

'''RDF formats only''': some RDF format return graphs instead of a triple sets. In ShareVDE the fourth dimension (the graph URI) is used for associating a triple to its provenance. As a consequence of that, if the request asks for a format which provides "triples" level info, it will get a "merged" view of the triples coming from all provenances, without any indication about the provenance itself.

In the example below, the requested format is n-triples: <syntaxhighlight>
<https://svde.org/works/731631362144813> <http://id.loc.gov/ontologies/bibframe/expressionOf> <https://svde.org/opuses/401> .
<https://svde.org/title_996/52f8c9bb-4545-3da1-82f9-e40e6f827014> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://id.loc.gov/ontologies/bibframe/Title> .
<https://svde.org/title_996/52f8c9bb-4545-3da1-82f9-e40e6f827014> <http://www.w3.org/2000/01/rdf-schema#label> "Alice's adventures in Wonderland" .
<https://svde.org/opuses/401> <http://id.loc.gov/ontologies/bibframe/title> <https://svde.org/title_996/52f8c9bb-4545-3da1-82f9-e40e6f827014> .
<https://svde.org/opuses/401> <http://www.loc.gov/mads/rdf/v1#authoritativeLabel> "Alice's adventures in Wonderland" .
<https://svde.org/opuses/401> <http://id.loc.gov/ontologies/bibframe/hasExpression> <https://svde.org/works/731631362144813> .
...
</syntaxhighlight>if instead the requestor asks for a format which includes also the 4th dimension, the resultset will contain the provenance information associated to each triple. See the same resource above using a TriX format: <syntaxhighlight lang="xml">
<trix xmlns="http://www.w3.org/2004/03/trix/trix-1/">
<graph>
<uri>https://svde.org/agents/BL</uri>
<triple>
<uri>https://svde.org/works/731631362144813</uri>
<uri>http://id.loc.gov/ontologies/bibframe/expressionOf</uri>
<uri>https://svde.org/opuses/401</uri>
</triple>
<triple>
<uri>https://svde.org/title_996/52f8c9bb-4545-3da1-82f9-e40e6f827014</uri>
<uri>http://www.w3.org/1999/02/22-rdf-syntax-ns#type</uri>
<uri>http://id.loc.gov/ontologies/bibframe/Title</uri>
</triple>
...
</graph>
<graph>
<uri>https://svde.org/agents/UALBERTA</uri>
<triple>
<uri>https://svde.org/works/731631362144813</uri>
<uri>http://id.loc.gov/ontologies/bibframe/expressionOf</uri>
<uri>https://svde.org/opuses/401</uri>
</triple>
...
</syntaxhighlight>There are three ways of negotiating the representation between the client and the server. The following sections describe them.

===Path Extension===
The idea of this approach is: each URL returns a given resource (note a collection is still a resource, although it is actually a set of resources); if the client wants to get back a given representation of that resource, it just needs to suffix the URL using one of the available extensions.

Examples:

*''<nowiki>https://svde.org/opuses/401.json</nowiki>''
*''<nowiki>https://svde.org/opuses/401.rdf</nowiki>''
*''<nowiki>https://svde.org/opuses/401.ttl</nowiki>''
*''<nowiki>https://svde.org/opuses/401.nt</nowiki>''
*''<nowiki>https://svde.org/opuses/401.nq</nowiki>''
*''<nowiki>https://svde.org/opuses/401.trix</nowiki>''
*''<nowiki>https://svde.org/opuses.xml?q=opuses+whose+title+contains+alice</nowiki>''

The following table lists the available extensions and the corresponding format.
{| class="wikitable" style="width:50%;" data-ve-attributes="{"style":"width:50%;"}"
!'''Suffix'''
!'''Format'''
|-
|.json
|JSON (default)
|-
|.jsonld
|JSON-LD
|-
|.rdf
|RDF/XML
|-
|.xml
|RDF/XML
|-
|.nt
|N-Triples
|-
|.n3
|Notation 3
|-
|.ttl
|Turtle
|-
|.nq
|N-Quads
|-
|.trix
|TriX
|-
|.trig
|TriG
|-
|.mrc
|MARC (Binary)
|-
|.marcxml
|MARCXML
|-
|.ris
|RIS
|}
Note: in case the requested suffix is not in the table above, the default format is JSON. <references />
===Request Parameter===
The client can ask for a specific format by appending a "format" request parameter. The value of that parameter must be one of the suffixes listed in the previous paragraph (without the beginning .).

Examples:

*''<nowiki>https://svde.org/opuses/401?format=json</nowiki>''
*''<nowiki>https://svde.org/opuses/401?format=rdf</nowiki>''
*''<nowiki>https://svde.org/opuses/401?format=ttl</nowiki>''
*''<nowiki>https://svde.org/opuses/401?format=nt</nowiki>''
*''<nowiki>https://svde.org/opuses/401?format=nq</nowiki>''
*''<nowiki>https://svde.org/opuses/401?format=trix</nowiki>''
*''<nowiki>https://svde.org/opuses.xml?format=json&q=opuses+whose+title+contains+alice</nowiki>''

Note in case the request parameter contains an unknown format, a "406 Not Acceptable" error is returned.

===The "Accept" Header===
The <code style="box-sizing: border-box; background-color: rgb(244, 244, 244); -webkit-box-decoration-break: clone; font-family: consolas, "Liberation Mono", courier, monospace; padding: 0px 3px; white-space: nowrap; overflow-wrap: break-word; text-decoration-skip-ink: none;">Accept</code> header lists the MIME types of media resources that the agent is willing to process. Although in the 99% of scenarios it consists of a single value (the requested media type), the accepted format is a comma-separated list of MIME types, each combined with a quality factor, that is a parameter indicating the relative degree of relevance between the specified MIME types.

Examples:

*<nowiki>*/* (JSON will be chosen in this case)</nowiki>
*text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9

In case one value is indicated in the Accept header, if that is supported (see the table below) that format is returned, otherwise a "406 Not Acceptable" error is returned.

The following table lists the supported media types.
{| class="wikitable" style="width:50%;" data-ve-attributes="{"style":"width:50%;"}"
!'''Suffix'''
!'''Format'''
|-
|*/*
|JSON (default)
|-
|application/json
|JSON (default)
|-
|application/ld+json
|JSON-LD
|-
|application/rdf+xml
|RDF/XML
|-
|application/xml
|RDF/XML
|-
|application/n-triples
|N-Triples
|-
|text/rdf+n3
|Notation 3
|-
|text/turtle
|Turtle
|-
|application/n-quads
|N-Quads
|-
|application/trix
|TriX
|-
|application/trig
|TriG
|-
|application/marc
|MARC (Binary)
|-
|application/marcxml
|MARCXML
|-
|application/x-research-info-systems
|RIS
|}