Last edited 4 months ago
by Serena Cericola

Share-VDE REST API: Content Negotiation


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.

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

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

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:

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

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:

  • https://svde.org/opuses/401.json
  • https://svde.org/opuses/401.rdf
  • https://svde.org/opuses/401.ttl
  • https://svde.org/opuses/401.nt
  • https://svde.org/opuses/401.nq
  • https://svde.org/opuses/401.trix
  • https://svde.org/opuses.xml?q=opuses+whose+title+contains+alice

The following table lists the available extensions and the corresponding format.

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.

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:

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

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

The "Accept" Header

The Accept 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:

  • */* (JSON will be chosen in this case)
  • 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.

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