Introduction

eccenca DataPlatform APIs can be used to import, export, query and extract information from graphs as well as to check access conditions.

This section describes common characteristics and features of all provided APIs.

Media Types

The default media type of most responses is application/json. Other possible response media types can be reached by changing the Accept header of the request. Alternatively, the desired response media type can be expressed in the request URI.

Possible values of this HTTP header field are API dependent and listed as part of the specific HTTP method.

Dependent on the specific API, eccenca DataPlatform works with the following application media types which correspond to the following specification documents:

Media TypeSpecification Document
application/x-www-form-urlencodedHTML 4.01 Specification, Forms
application/jsonThe JavaScript Object Notation (JSON) Data Interchange Format
application/ld+jsonJSON-LD 1.0
text/turtleRDF 1.1 Turtle - Terse RDF Triple Language
application/n-triplesRDF 1.1 N-Triples - A line-based syntax for an RDF graph
application/rdf+xmlRDF 1.1 XML Syntax
application/n-quadsRDF 1.1 N-Quads
application/trigRDF 1.1 TriG
application/sparql-querySPARQL 1.1 Query Language
application/sparql-updateSPARQL 1.1 Update
application/sparql-results+jsonSPARQL 1.1 Query Results JSON Format
application/sparql-results+xmlSPARQL Query Results XML Format (Second Edition)
text/csvSPARQL 1.1 Query Results CSV and TSV Formats
text/tab-separated-valuesSPARQL 1.1 Query Results CSV and TSV Formats
application/vnd.openxmlformats-officedocument.spreadsheetml.sheetMicrosoft Office Excel (.xlsx) format
application/problem+jsonProblem Details for HTTP APIs

Media type request by URI

The desired response media type can be requested by adding a format query parameter. The parameter value is interpreted as a media type abbreviation that is expanded to a proper media type string. eccenca DataPlatform maps the following abbreviations to media types it supports:

AbbreviationMedia Type
rdfapplication/rdf+xml
ttltext/turtle
jsonldapplication/ld+json
ntapplication/n-triples
trigapplication/trig
nqapplication/n-quads
srjapplication/sparql-results+json
srxapplication/sparql-results+xml
csvtext/csv
tsvtext/tab-separated-values

Thus, for example, a request to /proxy/default/graph with the Accept header value text/turtle and a request to /proxy/default/graph?format=ttl express the same intent for the media type of the response.

If both this format query parameter and an Accept header is present in a request, the parameter value takes precedence.

Usage of media type request by URI can be useful to create browser links that will express an intent for the media type of the response.

Security Schemes

The default security scheme is OAuth 2.0.
However, this can be changed in the configuration.

SPARQL result set streaming

The SPARQL proxy pipes the results of SPARQL queries directly from the underlying data endpoint to the request client. This however does not always apply for CONSTRUCT queries.

The result of a CONSTRUCT query is a set of statements. RDF graph serialization formats tend to group the information for compactness - e.g. in Turtle, all statements for a subject are written together - avoiding subject and subject-predicate repetition, for which it is necessary to have the complete result set at disposal.

Therefore, before sending the result to the request client, the complete result is loaded and then serialized. This creates a potential danger whenever a large result set is build and could lead to overload of the server.

There is however one serialization format (the N-Triples format) which is streaming friendly and that should always be used whenever large result sets are expected.

SPARQL default graph & RDF dataset

Default graph

The definition of the RDF dataset of a query in the SPARQL 1.1 specification leads to problems regarding the default graph of a SPARQL service. On one hand it is defined that:

A SPARQL query is executed against an RDF dataset which represents a collection of graphs. An RDF dataset comprises one graph, the default graph, which does not have a name, and zero or more named graphs, where each named graph is identified by an IRI.

Furthermore, it says:

A SPARQL query may specify the dataset to be used for matching by using the FROM clause and the FROM NAMED clause to describe the RDF dataset. If a query provides such a dataset description, then it is used in place of any dataset that the query service would use if no dataset description is provided in a query. The RDF dataset may also be specified in a SPARQL protocol request, in which case the protocol description overrides any description in the query itself. A query service may refuse a query request if the dataset description is not acceptable to the service.

The FROM and FROM NAMED keywords allow a query to specify an RDF dataset by reference; they indicate that the dataset should include graphs that are obtained from representations of the resources identified by the given IRIs (i.e. the absolute form of the given IRI references). The dataset resulting from a number of FROM and FROM NAMED clauses is:

  • a default graph consisting of the RDF merge of the graphs referred to in the FROM clauses, and
  • a set of (IRI, graph) pairs, one from each FROM NAMED clause.

If there is no FROM clause, but there is one or more FROM NAMED clauses, then the dataset includes an empty graph for the default graph.

That means the default graph of a SPARQL service cannot be explicitly referenced in the RDF dataset of a SPARQL query using FROM / FROM NAMED.

For this reason, DataPlatform does not allow the manipulation of the service's default graph.

To enforce this policy, the following restriction applies to incoming SPARQL 1.1 Update queries:

  • Update queries (INSERT DATA, DELETE DATA and DELETE/INSERT) targeted against the service's default graph will not be accepted by returning an HTTP 400 Bad Request status code.

Default RDF dataset

The interpretation of the RDF dataset of a query differs between various SPARQL service implementations (as shown here).

In the case a query declares no RDF dataset, DataPlatform uses the following default RDF dataset declaration to provide a uniform behavior for all supported SPARQL services:

  • The default graph is the union (RDF Merge graph) of all named graphs the user is allowed to access.
  • The set of named graphs contains all named graphs the user is allowed to access.


Data Endpoints (/proxy)

A collection of provided semantic data endpoints. Each endpoint is equipped with a set of APIs.

<!-- resource --> <!-- resource -->

SPARQL endpoint (/{endpointId})

Full URL: /proxy/{endpointId}

A specific SPARQL endpoint. Every endpoint is identified by an endpointId URI path parameter.

URI parameters:

  • endpointId, required:

    • type: (string)

Valid HTTP methods are:

GET

Returns metadata of the endpoint. Currently, the list of visible graphs contained by the store, together with their write access level.

Response

The expected response:

  • HTTP Status Code 200:

    • Successful response. The result's JSON schema is as follows:
{
  "definitions": {},
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": [
    "graphs"
  ],
  "properties": {
    "graphs": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "iri",
          "writeable"
        ],
        "properties": {
          "iri": {
            "type": "string",
            "examples": [
              "urn:graph:example"
            ],
            "pattern": "^(.+)$"
          },
          "writeable": {
            "type": "boolean",
            "default": false,
            "examples": [
              false, true
            ]
          }
        }
      }
    }
  }
}
-   **application/json**:

    

    -   example:
    
        ```
        {
          "graphs": [
            {
              "iri": "urn:graph:A",
              "writeable": false
            },
            {
              "iri": "urn:graph:B",
              "writeable": true
            }
          ]
        }
        
        ```
<!-- resource -->

SPARQL 1.1 Query (/sparql)

Full URL: /proxy/{endpointId}/sparql

The query operation is used to send a SPARQL 1.1 Query and receive its results. The query operation MUST be invoked with either the HTTP GET or HTTP POST method. Client requests for this operation must include exactly one SPARQL query string (parameter name: query) and may include zero or more default graph URIs (parameter name: default-graph-uri) and named graph URIs (parameter name: named-graph-uri). The response to a query request is either the SPARQL XML Results Format, the SPARQL JSON Results Format, the SPARQL CSV/TSV Results Format, or an RDF serialization, depending on the query form and content negotiation.

Valid HTTP methods are:

GET - SPARQL query via HTTP GET

SPARQL query via HTTP GET and query parameters

Query Parameters

This method accepts the following query parameters:

  • cdTarget:

    If present, a Content-Disposition header will be provided. If non-empty, the filename will be the value of the parameter, otherwise the filename will be 'download'.

    • type: (string)
  • format:

    the media type abbreviation to request a specific response format

    • type: (string)
  • query, required:

    A valid SPARQL 1.1 Query string as described in the SPARQL 1.1 Query Language

    • type: (string)

    • example:

      CONSTRUCT ?class WHERE {?s a ?class}
      
      
  • default-graph-uri:

    may include zero or more default graph URIs

    • type: (string)
  • named-graph-uri:

    may include zero or more named graph URIs

    • type: (string)
  • owlImportsResolution:

    Enable/disable OWL imports resolution for this query

    • type: (boolean)
Header Fields

This method pays attention to the following HTTP header fields:

  • Accept:

    Content-Types that are acceptable for the response.

    • type: (one of application/json, application/ld+json, application/n-triples, application/rdf+json, application/rdf+xml, application/sparql-results+json, application/sparql-results+xml, application/xml, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, text/csv, text/html, text/plain, text/tab-separated-values, text/turtle)

    • example:

      text/turtle
      
Response

The expected response:

  • HTTP Status Code 200:

    • Returns the result of the SPARQL query, which will either be a result set (in case of SELECT & ASK queries) or an RDF model (in case of CONSTRUCT & DESCRIBE queries)

    • text/turtle:

      • example:

        PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
        PREFIX owl: <http://www.w3.org/2002/07/owl#>
        PREFIX example: <http://example.org/>
        example:class rdf:type owl:Class .
        example:instance rdf:type example:class .
        
        
  • HTTP Status Code 503:

    • The connection pool to the database is overloaded, retry in a few (milli)seconds.

POST - SPARQL query via HTTP POST

SPARQL query via POST directly with unencoded SPARQL query string as body OR with URL-encoded, ampersand-separated query parameters.

Query Parameters

This method accepts the following query parameters:

  • cdTarget:

    If present, a Content-Disposition header will be provided. If non-empty, the filename will be the value of the parameter, otherwise the filename will be 'download'.

    • type: (string)
  • format:

    the media type abbreviation to request a specific response format

    • type: (string)
  • default-graph-uri:

    May include zero or more default graph URIs. Do only use together with application/sparql-query body.

    • type: (string)
  • named-graph-uri:

    May include zero or more named graph URIs. Do only use together with application/sparql-query body.

    • type: (string)
  • owlImportsResolution:

    Enable/disable OWL imports resolution for this query

    • type: (boolean)
Header Fields

This method pays attention to the following HTTP header fields:

  • Accept:

    Content-Types that are acceptable for the response.

    • type: (one of application/json, application/ld+json, application/n-triples, application/rdf+json, application/rdf+xml, application/sparql-results+json, application/sparql-results+xml, application/xml, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, text/csv, text/html, text/plain, text/tab-separated-values, text/turtle)

    • example:

      application/sparql-results+json
      
Body

This method accepts the following body payloads:

  • application/x-www-form-urlencoded:

    • form parameters:

      • query, required:

        A valid SPARQL 1.1 Query string as described in the SPARQL 1.1 Query Language

        • type: (string)

        • example:

          SELECT ?comment WHERE {?s rdfs:comment ?comment}
          
          
      • default-graph-uri:

        may include zero or more default graph URIs

        • type: (string)
      • named-graph-uri:

        may include zero or more named graph URIs

        • type: (string)
      • additional-columns:

        Defines additional projection variables to be added to the provided SELECT query. The value (which must be an IRI) represents a property to be added to the result set target resource, which is (by convention) the first projection variable. Optional, applies to SELECT queries only, will lead to a bad request on other query types. The JSON schema is as follows:

      {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "minProperties": 1,
        "patternProperties": {
          "^(.+)$": {
            "type": "string",
            "pattern": "^(.+)$"
          }
        }
      }
      
      -   type: (string)    
      
      -   example:
      
          ```
          {
            "label": "http://www.w3.org/2000/01/rdf-schema#label",
            "prefLabel": "http://www.w3.org/2004/02/skos/core#prefLabel"
          }
          ```
      
      • distinct:

        Whether only distinct solutions should be returned. Optional, applies to SELECT queries only, will lead to a bad request on other query types.

        • type: (string)
      • filter:

        Defines additional SPARQL filters to be applied to the provided SELECT query. Only projection variables in scope can be filtered. Optional, applies to SELECT queries only, will lead to a bad request on other query types. The JSON schema is as follows:

      {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "array",
        "minItems": 1,
        "items": {
          "type": "object",
          "required": [
            "variable",
            "function"
          ],
          "properties": {
            "variable": {
              "type": "string",
              "pattern": "^(.+)$"
            },
            "function": {
              "type": "string",
              "enum": [
                "oneOf",
                "equals",
                "greaterThan",
                "lessThan",
                "contains",
                "startsWith",
                "endsWith",
                "language",
                "datatype",
                "isIri"
              ]
            },
            "parameters": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "object",
                "required": [
                  "type",
                  "value"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["literal", "uri"]
                  },
                  "value": {
                    "type": "string",
                    "pattern": "^(.+)$"
                  },
                  "datatype": {
                    "type": "string",
                    "pattern": "^(.+)$"
                  },
                  "xml:lang": {
                    "type": "string",
                    "pattern": "^(.+)$"
                  }
                }
              }
            }
          }
        }
      }
      
      -   type: (string)    
      
      -   example:
      
          ```
          [
            {
              "variable": "s",
              "function": "oneOf",
              "parameters": [
                {
                  "type": "uri",
                  "value": "urn:some:resource"
                },
                {
                  "type": "uri",
                  "value": "urn:another:resource"
                }
              ]
            },
            {
              "variable": "o",
              "function": "lessThan",
              "parameters": [
                {
                  "type": "literal",
                  "value": "100",
                  "datatype": "http://www.w3.org/2001/XMLSchema#long"
                }
              ]
            }
          ]
      
          ```
      
      • limit:

        Pagination parameter, puts an upper bound on the number of solutions returned. The parameter value must be non-negative. Optional, applies to SELECT queries only, will lead to a bad request on other query types.

        • type: (integer)
      • offset:

        Pagination parameter, causes the solutions generated to start after the specified number of overall solutions. The parameter value must be non-negative. Optional, applies to SELECT queries only, will lead to a bad request on other query types.

        • type: (integer)
      • timeout:

        The maximal amount of time (in milliseconds) that a query should run until the execution is aborted. If none provided, the default timeout of the quad store applies.

        • type: (integer)
      • order-by:

        Defines the result set ordering to be applied to the provided SELECT query. Optional, applies to SELECT queries only, will lead to a bad request on other query types. The JSON schema is as follows:

      {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "array",
        "minItems": 1,
        "items": {
          "type": "object",
          "required": [
            "variable",
            "modifier"
          ],
          "properties": {
            "variable": {
              "type": "string",
              "pattern": "^(.+)$"
            },
            "modifier": {
              "type": "string",
              "enum": [
                "ASC",
                "DESC"
              ]
            }
          }
        }
      }
      
      -   type: (string)    
      
      -   example:
      
          ```
          [
            {
              "variable": "age",
              "modifier": "DESC"
            },
            {
              "variable": "resource",
              "modifier": "ASC"
            }
          ]
      
          ```
      
      • projection:

        Defines the variables of the solutions in the result set. Variable names introduced by the additional-columns parameter can be included. Optional, applies to SELECT queries only, will lead to a bad request on other query types. The JSON schema is as follows:

      {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "array",
        "minItems": 1,
        "items": {
          "type": "string",
          "pattern": "^(.+)$"
        }
      }
      
      -   type: (string)    
      
      • search:

        Defines a search term to narrow the results of a SELECT query. The search term is considered as an array of blank-separated, case-insensitive string values (search tokens). These tokens will be logiclly conjuncted and evaluated in the triple store. In case of triples stores with full text search, these will be use. In case of stardog the search term will be cleaned from reserved chararcters and will have stop word employed. Only a limited Use the variables array to declare the projection variables to be searched. If no variables array is given, the search applies to all projection variables in scope. If a variable binds an IRI, the search applies to the label properties attached to the resource (IRI), too. If in-iris is set to true, then the search will also apply to IRIs (instead of the default behaviour which only applies to literals). Refer to section Configuration/SPARQL Endpoints/Making a SPARQL endpoint accessible via HTTP of the System Manual about how to configure the label properties to be considered. Optional, applies to SELECT queries only, will lead to a bad request on other query types. The JSON schema is as follows:

      {
        "definitions": {},
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "required": [
          "string"
        ],
        "properties": {
          "string": {
            "type": "string",
            "examples": [
              "term"
            ],
            "pattern": "^(.+)$"
          },
          "variables": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "examples": [
                "x",
                "y"
              ],
              "pattern": "^(.+)$"
            }
          },
          "in-iris": {
            "type": "boolean",
            "examples": [
              "false"
            ]
          }
        }
      }
      
      -   type: (string)    
      
      • total-count:

        Denotes that a count of all solutions fulfilling the query should be computed and returned instead of individual query solutions. If set to true, the result set returned will only contain a single query solution that binds uniquely the variable ?count to the integer value of the computed total count. Pagination parameters will not affect the count computed. Optional, applies to SELECT queries only, will lead to a bad request on other query types.

        • type: (string)
  • application/sparql-query:

    • example:

      CONSTRUCT ?class WHERE {?s a ?class}
      
      
Response

The expected response:

  • HTTP Status Code 200:

    • Returns the result of the SPARQL query, which will either be a result set (in case of SELECT & ASK queries) or an RDF model (in case of CONSTRUCT & DESCRIBE queries).

    • application/sparql-results+xml:

      • example:

        <?xml version='1.0' encoding='UTF-8'?>
        <sparql xmlns='http://www.w3.org/2005/sparql-results#'>
          <head>
            <variable name='greeting'/>
            <variable name='language'/>
          </head>
          <results>
            <result>
              <binding name='greeting'>
                <literal>Hello!</literal>
              </binding>
              <binding name='language'>
                <uri>http://www.lexvo.org/page/iso639-3/eng</uri>
              </binding>
            </result>
            <result>
              <binding name='greeting'>
                <literal>Hallo!</literal>
              </binding>
              <binding name='language'>
                <uri>http://www.lexvo.org/page/iso639-3/deu</uri>
              </binding>
            </result>
            <result>
              <binding name='greeting'>
                <literal>¡Hola!</literal>
              </binding>
              <binding name='language'>
                <uri>http://www.lexvo.org/page/iso639-3/spa</uri>
              </binding>
            </result>
          </results>
        </sparql>
        
        
    • application/sparql-results+json:

      • example:

        {
          "head": {
            "vars": [ "count" ]
          },
          "results": {
            "bindings": [
              {
                "count": {
                  "type": "literal",
                  "datatype": "http://www.w3.org/2001/XMLSchema#integer",
                  "value": "42"
                }
              }
            ]
          }
        }
        
        
    • text/turtle:

      • example:

        PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
        PREFIX owl: <http://www.w3.org/2002/07/owl#>
        PREFIX example: <http://example.org/>
        example:class rdf:type owl:Class .
        example:instance rdf:type example:class .
        
        
  • HTTP Status Code 503:

    • The connection pool to the database is overloaded, retry in a few (milli)seconds.
<!-- resource -->

Framed SPARQL 1.1 CONSTRUCT Query (/framed)

Full URL: /proxy/{endpointId}/sparql/framed

The query operation is used to send a SPARQL 1.1 CONSTRUCT Query and a JSON-LD frame and receive the results of the CONSTRUCT query with applied frame. The query operation MUST be invoked with the HTTP POST method. Client requests for this operation must include exactly one SPARQL query string (parameter name: query) and may include zero or more default graph URIs (parameter name: default-graph-uri) and named graph URIs (parameter name: named-graph-uri). The response to a framed CONSTRUCT query request is serialized in the JSON-LD 1.1 Format.

Valid HTTP methods are:

POST - Framed SPARQL CONSTRUCT query via HTTP POST

Framed SPARQL CONSTRUCT query via HTTP POST with URL-encoded, ampersand-separated query parameters

Query Parameters

This method accepts the following query parameters:

  • cdTarget:

    If present, a Content-Disposition header will be provided. If non-empty, the filename will be the value of the parameter, otherwise the filename will be 'download'.

    • type: (string)
Header Fields

This method pays attention to the following HTTP header fields:

  • Accept:

    Content-Types that are acceptable for the response.

    • type: (one of application/ld+json)

    • example:

      application/ld+json
      
Body

This method accepts the following body payloads:

  • application/x-www-form-urlencoded:

    • form parameters:

      • query, required:

        A valid SPARQL 1.1 CONSTRUCT Query string as described in the SPARQL 1.1 Query Language

        • type: (string)
      • default-graph-uri:

        may include zero or more default graph URIs

        • type: (string)
      • named-graph-uri:

        may include zero or more named graph URIs

        • type: (string)
      • owlImportsResolution:

        Enable/disable OWL imports resolution for this query

        • type: (boolean)
      • frame:

        An optional JSON-LD frame used to force a specific JSON-LD tree layout.

        • type: (string)
Response

The expected response:

  • HTTP Status Code 200:

    • Returns the result of the SPARQL CONSTRUCT query, which will be an RDF model in JSON-LD syntax.

    • application/ld+json:

      • example:

        {
          "@context": {
            "ex": "http://example.org/vocab#"
          },
          "@graph": [
            {
              "@id": "http://example.org/library",
              "@type": "ex:Library"
            }
          ]
        }
        
        
  • HTTP Status Code 400:

    • The server cannot or will not process the request due to a malformed query or frame.
  • HTTP Status Code 503:

    • The connection pool to the database is overloaded, retry in a few (milli)seconds.
<!-- resources:end --> <!-- resources:end --> <!-- resource -->

SPARQL 1.1 Update (/update)

Full URL: /proxy/{endpointId}/update

The update operation is used to send a SPARQL 1.1 update request. The update operation must be invoked using the HTTP POST method. Client requests for this operation must include exactly one SPARQL update query string (parameter name: update) and may include zero or more default graph URIs (parameter name: using-graph-uri) and named graph URIs (parameter name: using-named-graph-uri). The response to an update request indicates success or failure of the request via HTTP response status code.

Valid HTTP methods are:

POST

SPARQL update query via POST directly with unencoded SPARQL update request string as body OR with URL-encoded, ampersand-separated query parameters

Query Parameters

This method accepts the following query parameters:

  • using-graph-uri:

    May include zero or more default graph URIs. Do only use together with application/sparql-update body.

    • type: (string)
  • using-named-graph-uri:

    May include zero or more named graph URIs. Do only use together with application/sparql-update body.

    • type: (string)
Body

This method accepts the following body payloads:

  • application/x-www-form-urlencoded:

    • form parameters:

      • update, required:

        URL-encoded SPARQL update query

        • type: (string)
      • using-graph-uri:

        URL-encoded default graph URI, may include zero or more

        • type: (string)
      • using-named-graph-uri:

        URL-encoded named graph URI, may include zero or more

        • type: (string)
  • application/sparql-update:

    • example:

      PREFIX foaf:  <http://xmlns.com/foaf/0.1/>
      
      WITH <http://example/addresses>
      DELETE { ?person foaf:givenName 'Bill' }
      INSERT { ?person foaf:givenName 'William' }
      WHERE {  ?person foaf:givenName 'Bill' } 
      
      
Response

The expected response:

  • HTTP Status Code 202:

    • The update query was processed successfully, however not fully. This typically means that further tasks still have to be post-processed.
  • HTTP Status Code 204:

    • The update query was processed successfully.
  • HTTP Status Code 400:

    • Bad request. Possible causes are either a wrong query syntax or a modification attempt of the default graph (refer to the section SPARQL Default Graph & RDF Dataset of the developer manual for more information regarding this topic)
  • HTTP Status Code 409:

    • Transaction aborted due to deadlock. Retrying should solve the problem.
  • HTTP Status Code 503:

    • The connection pool to the database is overloaded, retry in a few (milli)seconds.
<!-- resources:end --> <!-- resource -->

SPARQL 1.1 Graph Store (/graph)

Full URL: /proxy/{endpointId}/graph

This protocol specifies the semantics of HTTP operations for managing a Graph Store. In particular, it provides operations for removing, creating, and replacing RDF graph content as well as for adding RDF statements to existing RDF graph content.

Valid HTTP methods are:

GET

A request that uses the HTTP GET method MUST retrieve an RDF payload that is a serialization of the named graph paired with the graph IRI in the Graph Store.

Query Parameters

This method accepts the following query parameters:

  • cdTarget:

    If present, a Content-Disposition header will be provided. If non-empty, the filename will be the value of the parameter, otherwise the filename will be 'download'.

    • type: (string)
  • format:

    the media type abbreviation to request a specific response format

    • type: (string)
  • graph, required:

    A valid graph URI / IRI as described in SPARQL 1.1 Graph Store HTTP Protocol.

    • type: (string)

    • example:

      http://example.org
      
  • owlImportsResolution:

    Enable/disable OWL imports resolution for this query.

    • type: (boolean)
  • etag:

    If set to true, provide an ETag header in the response. The calculation of this value is time consuming. You should require it only if necessary.

    • type: (boolean)
  • timeout:

    The maximal amount of time (in milliseconds) that a request should run until the execution is aborted. If none provided, the default timeout of the quad store applies.

    • type: (integer)
Header Fields

This method pays attention to the following HTTP header fields:

  • Accept:

    Content-Types that are acceptable for the response.

    • type: (one of application/n-triples, text/turtle, application/rdf+xml)- default value: application/n-triples

    • example:

      text/turtle
      
Response

The expected response:

  • HTTP Status Code 200:

    • The request was processed successfully.
  • ETag:

    Present only if the etag parameter was set to true. Contains a weak ETag for the loaded graph. The tag consists of a hash/digest of the referenced graph.

    • type: (string)

    • text/turtle:

      • example:

        @prefix person: <http://example.org/person/> .
        @prefix relation: <http://example.org/relation/> .
        @prefix books: <http://example.org/books/> .
        person:Mark_Twain relation:author books:Huckleberry_Finn .
        
        
  • HTTP Status Code 204:

    • The request was processed successfully, but the graph is empty.
  • HTTP Status Code 400:

    • The server cannot or will not process the request due to a query parsing error (e.g., due to a defective graph URI).
  • HTTP Status Code 403:

    • The current user is not authorized to access the given graph.
  • HTTP Status Code 404:

    • The endpoint that has been requested could not be found.
  • HTTP Status Code 503:

    • The connection pool to the database is overloaded, retry in a few (milli)seconds.

This method is identical to GET except that the server MUST NOT return a message-body in the response. It is meant to be used for testing dereferenceable IRIs for validity, accessibility, and recent modification.

Query Parameters

This method accepts the following query parameters:

  • format:

    the media type abbreviation to request a specific response format

    • type: (string)
  • graph, required:

    A valid graph URI / IRI as described in SPARQL 1.1 Graph Store HTTP Protocol.

    • type: (string)

    • example:

      http://example.org
      
  • owlImportsResolution:

    Enable/disable OWL imports resolution for this query.

    • type: (boolean)
  • etag:

    If set to true, provide an ETag header in the response. The calculation of this value is time consuming. You should require it only if necessary.

    • type: (boolean)
  • timeout:

    The maximal amount of time (in milliseconds) that a request should run until the execution is aborted. If none provided, the default timeout of the quad store applies.

    • type: (integer)
Response

The expected response:

  • HTTP Status Code 200:

    • The request was processed successfully.
  • ETag:

    Present only if the etag parameter was set to true. Contains a weak ETag for the loaded graph. The tag consists of a hash/digest of the referenced graph.

    • type: (string)
  • HTTP Status Code 204:

    • The request was processed successfully, but the graph is empty.
  • HTTP Status Code 400:

    • The server cannot or will not process the request due to a query parsing error (e.g., due to a defective graph URI).
  • HTTP Status Code 403:

    • The current user is not authorized to access the given graph.
  • HTTP Status Code 404:

    • The endpoint that has been requested could not be found.
  • HTTP Status Code 503:

    • The connection pool to the database is overloaded, retry in a few (milli)seconds.

DELETE

A request that uses the HTTP DELETE method SHOULD delete the RDF graph content identified by either the request or encoded IRI.

Query Parameters

This method accepts the following query parameters:

Response

The expected response:

  • HTTP Status Code 204:

    • The request was processed successfully, but no content was returned.
  • HTTP Status Code 400:

    • The server cannot or will not process the request due to a query parsing error (e.g., due to a defective graph URI).
  • HTTP Status Code 403:

    • The current user is not authorized to access the given graph.
  • HTTP Status Code 404:

    • The endpoint that has been requested could not be found.
  • HTTP Status Code 503:

    • The connection pool to the database is overloaded, retry in a few (milli)seconds.

POST

Stores the given tuples in the underlying endpoint. If triples are provided, they are stored in the given graph. If a quad format is used, the graph URI be set as the target graph of the unnamed graph; all other quads will be stored as is.

Query Parameters

This method accepts the following query parameters:

  • format:

    the media type abbreviation to request a specific response format

    • type: (string)
  • graph, required:

    A valid graph URI / IRI as described in SPARQL 1.1 Graph Store HTTP Protocol.

    • type: (string)

    • example:

      http://example.org
      
  • replace:

    This optional (non-standard) parameter can be used to trigger a delete operation before storing the data. This operation logic is then equivalent to a PUT operation, but is adequate for restrictive environments (e.g. restrictive HTTP proxies which limit the accepted HTTP operations). If none of those restrictions apply, the use of the PUT method is recommended for standard compliance.

    • type: (boolean)
Header Fields

This method pays attention to the following HTTP header fields:

  • Content-Type, required:

    This header MUST be used to either to define the media type of the RDF data to be stored or to specify that the data to be stored is provided as multipart/form-data.

    • type: (string)
Body

This method accepts the following body payloads:

  • text/turtle:

    • example:

      @prefix person: <http://example.org/person/> .
      @prefix relation: <http://example.org/relation/> .
      @prefix books: <http://example.org/books/> .
      person:Mark_Twain relation:author books:Huckleberry_Finn .
      
      
  • application/n-triples:

    • example:

      <http://example.org/person/Mark_Twain> <http://example.org/relation/author> <http://example.org/books/Huckleberry_Finn> .
      
      
  • application/rdf+xml:

    • example:

      <?xml version="1.0" encoding="utf-8"?>
      <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
        <rdf:Description rdf:about="http://example.org/person/Mark_Twain">
          <ns0:author xmlns:ns0="http://example.org/relation/" rdf:resource="http://example.org/books/Huckleberry_Finn"/>
        </rdf:Description>
      </rdf:RDF>
      
      
  • application/ld+json:

    • example:

      {
        "@context": {
          "ns0": "http://example.org/relation/",
          "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
          "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
          "xsd": "http://www.w3.org/2001/XMLSchema#"
        },
        "@id": "http://example.org/person/Mark_Twain",
        "ns0:author": {
          "@id": "http://example.org/books/Huckleberry_Finn"
        }
      }
      
      
  • application/n-quads:

    • example:

      <urn:spiderman> <urn:enemyOf> <urn:green-goblin> <graph:spiderman> .
      
      
  • application/trig:

    • example:

      @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
      @prefix dc: <http://purl.org/dc/terms/> .
      @prefix foaf: <http://xmlns.com/foaf/0.1/> .
          {
            <http://example.org/bob> dc:publisher "Bob" .
            <http://example.org/alice> dc:publisher "Alice" .
          }
      <http://example.org/bob>
          {
             <http://example.org/bob> foaf:name "Bob" .
             <http://example.org/bob> foaf:mbox <mailto:bob@oldcorp.example.org> .
             <http://example.org/bob> foaf:knows <http://example.org/alice> .
          }
      <http://example.org/alice>
          {
             <http://example.org/alice> foaf:name "Alice" .
             <http://example.org/alice> foaf:mbox <mailto:alice@work.example.org> .
          }
      
      
  • multipart/form-data:

    • form parameters:

      • file, required:

        The uploaded Turtle (.ttl), NTriples (.nt), RDF/XML (.rdf or .owl), JSON-LD (.jsonld), N-Quads (.nq) or TriG (.trig) file content. Max filesize is set to 1024MB which can be adjusted in the config.

        • type: (file)
Response

The expected response:

  • HTTP Status Code 204:

    • The request was processed successfully, but no content was returned.
  • HTTP Status Code 400:

    • The server cannot or will not process the request due to a query parsing error (e.g., due to a defective graph URI).
  • HTTP Status Code 403:

    • The current user is not authorized to access the given graph.
  • HTTP Status Code 404:

    • The endpoint that has been requested could not be found.
  • HTTP Status Code 409:

    • Transaction aborted due to deadlock. Retrying should solve the problem.
  • HTTP Status Code 415:

    • The given media type is not supported.
  • HTTP Status Code 503:

    • The connection pool to the database is overloaded, retry in a few (milli)seconds.

PUT

A request that uses the HTTP PUT method MUST store the enclosed RDF payload as RDF graph content. The given RDF payload MUST be encoded as UTF-8.

Query Parameters

This method accepts the following query parameters:

Header Fields

This method pays attention to the following HTTP header fields:

  • Content-Type, required:

    This header MUST be used to either to define the media type of the RDF data to be stored or to specify that the data to be stored is provided as multipart/form-data.

    • type: (string)
Body

This method accepts the following body payloads:

  • text/turtle:

    • example:

      @prefix person: <http://example.org/person/> .
      @prefix relation: <http://example.org/relation/> .
      @prefix books: <http://example.org/books/> .
      person:Mark_Twain relation:author books:Huckleberry_Finn .
      
      
  • application/n-triples:

    • example:

      <urn:Mark_Twain> <urn:author> <urn:Huckleberry_Finn> .
      
      
  • application/rdf+xml:

    • example:

      <?xml version="1.0" encoding="utf-8"?>
      <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
        <rdf:Description rdf:about="http://example.org/person/Mark_Twain">
          <ns0:author xmlns:ns0="http://example.org/relation/" rdf:resource="http://example.org/books/Huckleberry_Finn"/>
        </rdf:Description>
      </rdf:RDF>
      
      
  • application/ld+json:

    • example:

      {
        "@context": {
          "ns0": "http://example.org/relation/",
          "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
          "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
          "xsd": "http://www.w3.org/2001/XMLSchema#"
        },
        "@id": "http://example.org/person/Mark_Twain",
        "ns0:author": {
          "@id": "http://example.org/books/Huckleberry_Finn"
        }
      }
      
      
  • application/n-quads:

    • example:

      <urn:spiderman> <urn:enemyOf> <urn:green-goblin> <graph:spiderman> .
      
      
  • application/trig:

    • example:

      @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
      @prefix dc: <http://purl.org/dc/terms/> .
      @prefix foaf: <http://xmlns.com/foaf/0.1/> .
          {
            <http://example.org/bob> dc:publisher "Bob" .
            <http://example.org/alice> dc:publisher "Alice" .
          }
      <http://example.org/bob>
          {
             <http://example.org/bob> foaf:name "Bob" .
             <http://example.org/bob> foaf:mbox <mailto:bob@oldcorp.example.org> .
             <http://example.org/bob> foaf:knows <http://example.org/alice> .
          }
      <http://example.org/alice>
          {
             <http://example.org/alice> foaf:name "Alice" .
             <http://example.org/alice> foaf:mbox <mailto:alice@work.example.org> .
          }
      
      
  • multipart/form-data:

    • form parameters:

      • file, required:

        The uploaded Turtle (.ttl), NTriples (.nt), RDF/XML (.rdf or .owl), JSON-LD (.jsonld), N-Quads (.nq) or TriG (.trig) file content. Max filesize is set to 1024MB which can be adjusted in the config.

        • type: (file)
Response

The expected response:

  • HTTP Status Code 204:

    • The request was processed successfully, but no content was returned.
  • HTTP Status Code 400:

    • The server cannot or will not process the request due to a query parsing error (e.g., due to a defective graph URI).
  • HTTP Status Code 403:

    • The current user is not authorized to access the given graph.
  • HTTP Status Code 404:

    • The endpoint that has been requested could not be found.
  • HTTP Status Code 409:

    • Transaction aborted due to deadlock. Retrying should solve the problem.
  • HTTP Status Code 415:

    • The given media type is not supported.
  • HTTP Status Code 503:

    • The connection pool to the database is overloaded, retry in a few (milli)seconds.
<!-- resources:end --> <!-- resource -->

Resource store (/resource)

Full URL: /proxy/{endpointId}/resource

Provides read and write operations for Concise Bound Description of RDF resources.

Valid HTTP methods are:

GET

Returns the Concise Bound Description of the requested resource in the given graph.

Query Parameters

This method accepts the following query parameters:

  • cdTarget:

    If present, a Content-Disposition header will be provided. If non-empty, the filename will be the value of the parameter, otherwise the filename will be 'download'.

    • type: (string)
  • format:

    the media type abbreviation to request a specific response format

    • type: (string)
  • resource, required:

    A valid resource URI.

    • type: (string)

    • example:

      http://example.org/person/Mark_Twain
      
  • graph, required:

    The URI of the graph containing the resource.

    • type: (string)

    • example:

      http://example.org/graph
      
Header Fields

This method pays attention to the following HTTP header fields:

  • Accept:

    Content-Types that are acceptable for the response.

    • type: (one of application/n-triples, text/turtle, application/rdf+xml, application/json+ld)- default value: application/n-triples

    • example:

      text/turtle
      
Response

The expected response:

  • HTTP Status Code 200:

    • The request was processed successfully
  • ETag:

    A weak ETag validator as specified in rfc2616.

    • type: (string)

    • example:

      W/"AdfEwfG"
      
    • text/turtle:

      • example:

        @prefix person: <http://example.org/person/> .
        @prefix relation: <http://example.org/relation/> .
        @prefix books: <http://example.org/books/> .
        person:Mark_Twain relation:author books:Huckleberry_Finn .
        
        
  • HTTP Status Code 204:

    • The request was processed successfully, but no information for the given parameters was found.
  • HTTP Status Code 400:

    • The server cannot or will not process the request due to a query parsing error (e.g., due to a defective graph URI).
  • HTTP Status Code 403:

    • The current user is not authorized to access the given graph.
  • HTTP Status Code 404:

    • The endpoint that has been requested could not be found.
  • HTTP Status Code 503:

    • The connection pool to the database is overloaded, retry in a few (milli)seconds.

HEAD

Equivalent to a GET request, but without a response body.

DELETE

Deletes the Concise Bound Description of the provided resource contained by the provided graph.

Query Parameters

This method accepts the following query parameters:

  • resource, required:

    A valid resource URI

    • type: (string)

    • example:

      http://example.org/person/Mark_Twain
      
  • graph, required:

    the URI of the graph containing the resource

    • type: (string)

    • example:

      http://example.org/graph
      
Response

The expected response:

  • HTTP Status Code 204:

    • The request was processed successfully and no content is provided as expected.

POST

Adds the given statements to the Concise Bound Description of the given resource in the supplied graph.

Query Parameters

This method accepts the following query parameters:

  • format:

    the media type abbreviation to request a specific response format

    • type: (string)
  • resource, required:

    A valid resource URI.

    • type: (string)

    • example:

      http://example.org/person/Mark_Twain
      
  • graph, required:

    The URI of the graph containing the resource.

    • type: (string)

    • example:

      http://example.org/graph
      
  • replace:

    This optional parameter can be used to trigger a delete operation before storing the data. This operation logic is then equivalent to a PUT operation, but is adequate for restrictive environments (e.g. restrictive HTTP proxies which limit the accepted HTTP operations). If none of those restrictions apply, the use of the PUT method is recommended for standard compliance.

    • type: (boolean)

PUT

Replaces the Concise Bound Description of the given resource contained in the supplied graph.

Query Parameters

This method accepts the following query parameters:

  • format:

    the media type abbreviation to request a specific response format

    • type: (string)
  • resource, required:

    A valid resource URI.

    • type: (string)

    • example:

      http://example.org/person/Mark_Twain
      
  • graph, required:

    The URI of the graph containing the resource.

    • type: (string)

    • example:

      http://example.org/graph
      
Body

This method accepts the following body payloads:

  • text/turtle:

    • example:

      @prefix person: <http://example.org/person/> .
      @prefix relation: <http://example.org/relation/> .
      @prefix books: <http://example.org/books/> .
      person:Mark_Twain relation:author books:Huckleberry_Finn .
      
      
  • application/n-triples:

    • example:

      <urn:Mark_Twain> <urn:author> <urn:Huckleberry_Finn> .
      
      
  • application/rdf+xml:

    • example:

      <?xml version="1.0" encoding="utf-8"?>
      <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
        <rdf:Description rdf:about="http://example.org/person/Mark_Twain">
          <ns0:author xmlns:ns0="http://example.org/relation/" rdf:resource="http://example.org/books/Huckleberry_Finn"/>
        </rdf:Description>
      </rdf:RDF>
      
      
  • application/ld+json:

    • example:

      {
        "@context": {
          "ns0": "http://example.org/relation/",
          "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
          "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
          "xsd": "http://www.w3.org/2001/XMLSchema#"
        },
        "@id": "http://example.org/person/Mark_Twain",
        "ns0:author": {
          "@id": "http://example.org/books/Huckleberry_Finn"
        }
      }
      
      
Response

The expected response:

  • HTTP Status Code 204:

    • The request was processed successfully, but no content was returned.
  • HTTP Status Code 400:

    • The server cannot or will not process the request due to a query parsing error (e.g., due to a defective graph URI).
  • HTTP Status Code 403:

    • The current user is not authorized to access the given graph.
  • HTTP Status Code 404:

    • The endpoint that has been requested could not be found.
  • HTTP Status Code 409:

    • Transaction aborted due to deadlock. Retrying should solve the problem.
  • HTTP Status Code 415:

    • The given media type is not supported.
  • HTTP Status Code 503:

    • The connection pool to the database is overloaded, retry in a few (milli)seconds.
<!-- resource -->

Framed Resource store (/framed)

Full URL: /proxy/{endpointId}/resource/framed

Provides Concise Bound Description read access of RDF resources in JSON-LD format. An optional JSON-LD frame can be provided to force a specific tree layout to the JSON-LD results.

Valid HTTP methods are:

POST

Returns the Concise Bound Description of the requested resource in the given graph.

Query Parameters

This method accepts the following query parameters:

  • cdTarget:

    If present, a Content-Disposition header will be provided. If non-empty, the filename will be the value of the parameter, otherwise the filename will be 'download'.

    • type: (string)
Header Fields

This method pays attention to the following HTTP header fields:

  • Accept:

    Content-Types that are acceptable for the response.

    • type: (one of application/json+ld)

    • example:

      application/json+ld
      
Body

This method accepts the following body payloads:

  • application/x-www-form-urlencoded:

    • form parameters:

      • resource, required:

        A valid resource URI.

        • type: (string)

        • example:

          http://example.org/person/Mark_Twain
          
      • graph, required:

        The URI of the graph containing the resource.

        • type: (string)

        • example:

          http://example.org/graph
          
      • frame:

        An optional JSON-LD frame used to force a specific JSON-LD tree layout.

        • type: (string)
Response

The expected response:

  • HTTP Status Code 200:

    • The request was processed successfully.
  • ETag:

    A weak ETag validator as specified in rfc2616.

    • type: (string)

    • example:

      W/"AdfEwfG"
      
    • application/ld+json:

      • example:

        {
          "@context": {
            "ns0": "http://example.org/relation/",
            "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
            "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
            "xsd": "http://www.w3.org/2001/XMLSchema#"
          },
          "@id": "http://example.org/person/Mark_Twain",
          "ns0:author": {
            "@id": "http://example.org/books/Huckleberry_Finn"
          }
        }
        
        
  • HTTP Status Code 204:

    • The request was processed successfully, but no information for the given parameters was found.
  • HTTP Status Code 400:

    • The server cannot or will not process the request due to a query parsing error (e.g., due to a defective graph URI).
  • HTTP Status Code 403:

    • The current user is not authorized to access the given graph.
  • HTTP Status Code 404:

    • The endpoint that has been requested could not be found.
  • HTTP Status Code 503:

    • The connection pool to the database is overloaded, retry in a few (milli)seconds.
<!-- resources:end --> <!-- resources:end --> <!-- resource -->

VOWL visualization data (/vowl)

Full URL: /proxy/{endpointId}/vowl

This endpoint provides WebVOWL visualization data for OWL data in a specific graph.

Valid HTTP methods are:

GET

Query Parameters

This method accepts the following query parameters:

Header Fields

This method pays attention to the following HTTP header fields:

  • Accept:

    Content-Types that are acceptable for the response.

    • type: (one of application/vowl+json)

    • example:

      application/vowl+json
      
Response

The expected response:

  • HTTP Status Code 200:

    • The request was processed successfully.

    • application/vowl+json:

      • example:

        {
          "_comment" : "Created with OWL2VOWL (version 0.3.4), http://vowl.visualdataweb.org",
          "header" : {
            "baseIris" : [ "http://example.org", "http://www.w3.org/2000/01/rdf-schema" ],
            "iri" : "No IRI set"
          },
          "namespace" : [ ],
          "metrics" : {
            "classCount" : 1,
            "objectPropertyCount" : 0,
            "datatypePropertyCount" : 0,
            "individualCount" : 1
          },
          "class" : [ {
            "id" : "0",
            "type" : "owl:Class"
          } ],
          "classAttribute" : [ {
            "iri" : "http://example.org/Class",
            "baseIri" : "http://example.org",
            "instances" : 0,
            "label" : {
              "IRI-based" : "Class"
            },
            "individuals" : [ {
              "iri" : "http://example.org/instance",
              "baseIri" : "http://example.org",
              "labels" : {
                "IRI-based" : "instance"
              }
            } ],
            "attributes" : [ "external" ],
            "id" : "0"
          } ]
        }
        
  • HTTP Status Code 400:

    • The server cannot or will not process the request due to a query parsing error (e.g., due to a defective graph URI).
  • HTTP Status Code 403:

    • The current user is not authorized to access the given graph.
  • HTTP Status Code 404:

    • The endpoint that has been requested could not be found.
  • HTTP Status Code 503:

    • The connection pool to the database is overloaded, retry in a few (milli)seconds.
<!-- resources:end --> <!-- resources:end --> <!-- resources:end -->

Accessible graphs (/graphs)

Get a list of graph URIs the requesting user is allowed to read or write.

<!-- resource --> <!-- resource -->

SPARQL endpoint (/{endpointId})

Full URL: /graphs/{endpointId}

A specific SPARQL endpoint. Every endpoint is identified by an endpointId URI path parameter.

URI parameters:

  • endpointId, required:

    • type: (string)
<!-- resource -->

Readable Graphs (/read)

Full URL: /graphs/{endpointId}/read

Valid HTTP methods are:

GET

A list of graph URIs the user is allowed to read (includes writable graphs)

Query Parameters

This method accepts the following query parameters:

  • graphUri:

    check read access for a specific graph, will return true if read is allowed, otherwise false

    • type: (string)

    • example:

      http://example.org/graphA
      
Response

The expected response:

  • HTTP Status Code 200:

    • application/json:

      • example:

        [
          "urn:readableGraphA",
          "urn:readableGraphB",
          "urn:writableGraphC"
        ]
        
        
<!-- resources:end --> <!-- resource -->

Writable Graphs (/write)

Full URL: /graphs/{endpointId}/write

Valid HTTP methods are:

GET

A list of graph URIs the user is allowed to write

Query Parameters

This method accepts the following query parameters:

  • graphUri:

    check write access for a specific graph, will return true if write is allowed, otherwise false

    • type: (string)

    • example:

      http://example.org/graphA
      
Response

The expected response:

  • HTTP Status Code 200:

    • application/json:

      • example:

        [
          "urn:writableGraphA",
          "urn:writableGraphB"
        ]
        
        
<!-- resources:end --> <!-- resources:end --> <!-- resources:end -->

Allowed actions (/actions)

Get a list of action URIs the requesting user is allowed to perform.

<!-- resource --> <!-- resource -->

SPARQL endpoint (/{endpointId})

Full URL: /actions/{endpointId}

A specific SPARQL endpoint. Every endpoint is identified by an endpointId URI path parameter.

URI parameters:

  • endpointId, required:

    • type: (string)

Valid HTTP methods are:

GET - Allowed actions

A list of action URIs the user is allowed to perform.

Query Parameters

This method accepts the following query parameters:

  • actionUri:

    Check for a specific action, will return true if the user is allowed to perform the action, otherwise false.

    • type: (string)

    • example:

      http://example.org/actionA
      
Response

The expected response:

  • HTTP Status Code 200:

    • application/json:

      • example:

        [
          "urn:actionA",
          "urn:actionB"
        ]
        
        
<!-- resources:end --> <!-- resources:end -->

UserInfo Endpoint (/userinfo)

Displays arbitrary user information, such as user name and account URI.

<!-- resource -->

UserInfo Endpoint (/userinfo)

Full URL: /userinfo

Valid HTTP methods are:

GET

Response

The expected response:

  • HTTP Status Code 200:

    • application/json:

      • example:

        {
          "accountName":"USERNAME",
          "uri":"https://ns.eccenca.com/USERNAME"
        }
        
        
<!-- resources:end -->

Authorization management API (/authorization)

API for authorization management. Access conditions can be managed using the provided methods. The requesting user must have the urn:elds-backend-actions-auth-access-control action granted to be able to use this API. Root users can manage any access condition.

<!-- resource --> <!-- resource -->

Access control refresh (/refresh)

Full URL: /authorization/refresh

Valid HTTP methods are:

GET

Reloads the access conditions model following the internal configuration parameters.

Response

The expected response:

  • HTTP Status Code 204:

    • The access conditions were successfully reloaded.
  • HTTP Status Code 403:

    • The user does not have permission to execute this action.
  • HTTP Status Code 500:

    • The access conditions could not be loaded, most likely due to an inconsistency in the new access conditions model. The active access conditions model stays unmodified.
<!-- resources:end --> <!-- resource -->

Access conditions management (/conditions)

Full URL: /authorization/conditions

This is an endpoint for management (read & write) of access conditions.

Valid HTTP methods are:

POST

Store a new access condition with the properties provided in the request body. A valid input access condition must contain the eccauth:AccessCondition type, at least one grant (any property defined as a sub-property of eccauth:isAllowed) and any number of requirements (any property defined as a sub-property of eccauth:requiresAttribute). Optionally, the access condition can be annotated with the properties rdfs:label and rdfs:comment. If present, the value of the property eccauth:requiresAccount must be either an IRI or a blank node with annotated eccauth:Account type and a single label. If present, the value of the property eccauth:requiresGroup must be either an IRI or a blank node with annotated eccauth:Group type and a single label. Further annotations will be rejected. The access condition must be anonymous (blank node as subject). Identifiers (IRIs) will be created by the server for valid blank node elements (access condition, accounts, groups).

Query Parameters

This method accepts the following query parameters:

Header Fields

This method pays attention to the following HTTP header fields:

  • Accept:

    Content-Types that are acceptable for the response.

    • type: (one of application/n-triples, text/turtle, application/rdf+xml, application/ld+json)- default value: application/n-triples

    • example:

      text/turtle
      
Body

This method accepts the following body payloads:

  • text/turtle:

    • example:

      @prefix : <https://ns.eccenca.com/> .
      @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
      @prefix eccauth: <https://vocab.eccenca.com/auth/> .
      [] a eccauth:AccessCondition ;
          eccauth:requiresGroup <urn:elds-backend-public-group> ;
          eccauth:requiresEndpointId "endpointId" ;
          eccauth:readGraph :GraphPublic ;
          rdfs:label "Public access condition on 'endpointId'" ;
      .
      
      
Response

The expected response:

  • HTTP Status Code 201:

    • Successful access condition creation. The response body contains the newly replaced access condition.
  • Location:

    Points to the IRI where the access condition can be loaded.

    • type: (string)

    • text/turtle:

      • example:

        @prefix : <https://ns.eccenca.com/> .
        @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
        @prefix eccauth: <https://vocab.eccenca.com/auth/> .
        @prefix dct: <http://purl.org/dc/terms/> .
        @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
        :PublicAccessCondition a eccauth:AccessCondition ;
            eccauth:requiresGroup <urn:elds-backend-public-group> ;
            eccauth:requiresEndpointId "endpointId" ;
            eccauth:readGraph :GraphPublic ;
            rdfs:label "Public access condition on 'endpointId'" ;
            dct:creator :username ;
            dct:created "2017-03-14T16:41:15Z"^^xsd:date ;
        .
        
        
  • HTTP Status Code 403:

    • The user is not allowed to store the access condition or does not have permission to execute this action. This can be caused either because the user is not allowed to add new conditions or because the access condition grants access to a resource to which the user has no grant allowance.
  • HTTP Status Code 405:

    • The access condition could not be added because the access conditions model is not modifiable.
  • HTTP Status Code 422:

    • The access condition is not valid.

PUT

Replaces the access condition with the properties provided in the request body. A valid input access condition must contain the eccauth:AccessCondition type, at least one grant (any property defined as a sub-property of eccauth:isAllowed) and any number of requirements (any property defined as a sub-property of eccauth:requiresAttribute). Optionally, the access condition can be annotated with the properties rdfs:label and rdfs:comment. If present, the value of the property eccauth:requiresAccount must be either an IRI or a blank node with annotated eccauth:Account type and a single label. If present, the value of the property eccauth:requiresGroup must be either an IRI or a blank node with annotated eccauth:Group type and a single label. Further annotations will be rejected. The access condition (identified by its IRI) must already exist in the store. A blank node is not allowed as the access condition resource identifier. Identifiers (IRIs) will be created by the server for valid blank node elements (accounts, groups).

Query Parameters

This method accepts the following query parameters:

  • format:

    the media type abbreviation to request a specific response format

    • type: (string)
  • resource, required:

    The IRI of the access condition to replace.

    • type: (string)

    • example:

      https://ns.eccenca.com/PublicAccessCondition
      
Header Fields

This method pays attention to the following HTTP header fields:

  • Accept:

    Content-Types that are acceptable for the response.

    • type: (one of text/turtle, application/n-triples, application/rdf+xml, application/ld+json)

    • example:

      text/turtle
      
Body

This method accepts the following body payloads:

  • text/turtle:

    • example:

      @prefix : <https://ns.eccenca.com/> .
      @prefix eccauth: <https://vocab.eccenca.com/auth/> .
      :PublicAccessCondition a eccauth:AccessCondition ;
          eccauth:requiresGroup <urn:elds-backend-public-group> ;
          eccauth:readGraph :GraphPublic ;
      .
      
      
Response

The expected response:

  • HTTP Status Code 200:

    • Successful access condition replacement. The response body contains the newly replaced access condition.

    • text/turtle:

      • example:

        @prefix : <https://ns.eccenca.com/> .
        @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
        @prefix eccauth: <https://vocab.eccenca.com/auth/> .
        @prefix dct: <http://purl.org/dc/terms/> .
        @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
        :PublicAccessCondition a eccauth:AccessCondition ;
            eccauth:requiresGroup <urn:elds-backend-public-group> ;
            eccauth:readGraph :GraphPublic ;
            dct:creator :username ;
            rdfs:label "Public access condition" ;
            dct:created "2017-03-14T16:41:15Z"^^xsd:date ;
        .
        
        
  • HTTP Status Code 403:

    • The user is not allowed to replace the access condition or does not have permission to execute this action. This can be caused either because the user is not allowed to add new conditions, because the access condition grants access to a resource to which the user has no grant allowance or because the access condition with the given IRI is not modifiable by the user.
  • HTTP Status Code 404:

    • The access condition does not exist.
  • HTTP Status Code 405:

    • The access condition could not be replaced because the access conditions model is not modifiable.
  • HTTP Status Code 422:

    • The access condition was not stored because it is not valid.

GET

Retrieve all access conditions manageable by the user or a specific one (see the resource parameter description).

Query Parameters

This method accepts the following query parameters:

  • format:

    the media type abbreviation to request a specific response format

    • type: (string)
  • resource:

    Retrieve only the access condition identified by the given IRI.

    • type: (string)

    • example:

      https://ns.eccenca.com/PublicAccessCondition
      
Header Fields

This method pays attention to the following HTTP header fields:

  • Accept:

    Content-Types that are acceptable for the response.

    • type: (one of application/n-triples, text/turtle, application/rdf+xml, application/ld+json)- default value: application/n-triples

    • example:

      text/turtle
      
Response

The expected response:

  • HTTP Status Code 200:

    • Successful retrieval of the requested access conditions.

    • text/turtle:

      • example:

        @prefix : <https://ns.eccenca.com/> .
        @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
        @prefix eccauth: <https://vocab.eccenca.com/auth/> .
        @prefix dct: <http://purl.org/dc/terms/> .
        @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
        :PublicAccessCondition a eccauth:AccessCondition ;
            eccauth:requiresGroup <urn:elds-backend-public-group> ;
            eccauth:readGraph :GraphPublic ;
            dct:creator :username ;
            rdfs:label "Public access condition" ;
            dct:created "2017-03-14T16:41:15Z"^^xsd:date ;
        .
        
        
  • HTTP Status Code 204:

    • The access conditions model is empty.
  • HTTP Status Code 403:

    • The user is not allowed to manage the access condition or does not have permission to execute this action.
  • HTTP Status Code 404:

    • The access condition does not exist.

DELETE

Delete an existing access condition with the given name.

Query Parameters

This method accepts the following query parameters:

  • resource, required:

    The IRI of the access condition to be deleted.

    • type: (string)

    • example:

      https://ns.eccenca.com/PublicAccessCondition
      
Response

The expected response:

  • HTTP Status Code 204:

    • Removal of the access condition was successful.
  • HTTP Status Code 403:

    • The user is not allowed to delete the access condition or does not have permission to execute this action.
  • HTTP Status Code 404:

    • The access condition does not exist.
  • HTTP Status Code 405:

    • The access condition could not be removed because the access conditions model is not modifiable.
<!-- resource -->

Access conditions management with JSON-LD frame support (/framed)

Full URL: /authorization/conditions/framed

Valid HTTP methods are:

POST

Retrieve manageable access conditions with a specific JSON-LD tree layout forced by the given frame.

Query Parameters

This method accepts the following query parameters:

  • resource:

    Retrieve only the access condition identified by the given IRI.

    • type: (string)

    • example:

      https://ns.eccenca.com/PublicAccessCondition
      
Body

This method accepts the following body payloads:

  • application/ld-frame+json:

    • example:

      {
        "@context": {
          "@vocab": "https://vocab.eccenca.com/auth/"
        },
        "@type": "AccessCondition"
      }
      
      
Response

The expected response:

  • HTTP Status Code 200:

    • Successful retrieval of the requested access condition(s).

    • application/ld+json:

      • example:

        {
          "@context":{
            "@vocab":"https://vocab.eccenca.com/auth/"
          },
          "@graph":[
            {
              "@id":"https://ns.eccenca.com/PublicAccessCondition",
              "@type":"AccessCondition",
              "http://purl.org/dc/terms/created":{
                "@type":"http://www.w3.org/2001/XMLSchema#date",
                "@value":"2017-03-14T16:41:15Z"
              },
              "http://purl.org/dc/terms/creator":{
                "@id":"https://ns.eccenca.com/username"
              },
              "http://www.w3.org/2000/01/rdf-schema#label":"Public access condition",
              "readGraph":{
                "@id":"urn:elds-backend-all-graphs"
              },
              "requiresGroup":{
                "@id":"urn:elds-backend-public-group"
              }
            }
          ]
        }
        
        
  • HTTP Status Code 204:

    • The access conditions model is empty.
  • HTTP Status Code 400:

    • The given JSON-LD frame is malformed.
  • HTTP Status Code 403:

    • The user is not allowed to manage the access condition or does not have permission to execute this action.
  • HTTP Status Code 404:

    • The access condition does not exist.
<!-- resources:end --> <!-- resources:end --> <!-- resources:end -->

Application health (/actuator/health)

Shows application health information.

<!-- resource -->

Application health (/actuator/health)

Full URL: /actuator/health

Valid HTTP methods are:

GET

Shows application health information to check the status of the application. Admin users will get a detailed status description, all others will see a simple ‘status’ message.

Response

The expected response:

  • HTTP Status Code 200:

    • application/json:

      • example:

        {
          status: "UP"
        }
        
        
<!-- resources:end -->

Application information (/actuator/info)

Displays arbitrary application info, such as program version etc.

<!-- resource -->

Application information (/actuator/info)

Full URL: /actuator/info

Valid HTTP methods are:

GET

Displays arbitrary application info, such as program version etc.

Response

The expected response:

  • HTTP Status Code 200:

    • application/json:

      • example:

        {
          name: "eccenca DataPlatform",
          version: "vX.X.X-XX-XXXXXXXX"
        }
        
        
<!-- resources:end -->

Application loggers (/actuator/loggers)

Allows the management of the application's logging levels. This endpoint is only accessible by root users (see section Root access of the System Manual).

<!-- resource -->

Application loggers (/actuator/loggers)

Full URL: /actuator/loggers

Valid HTTP methods are:

GET

Displays all accepted logging levels as well as the currently configured loggers.

Response

The expected response:

  • HTTP Status Code 200:

    • application/json:

      • example:

        {
          "levels":["OFF","ERROR","WARN","INFO","DEBUG","TRACE"],
          "loggers":{
            "ROOT":{"configuredLevel":"DEBUG","effectiveLevel":"DEBUG"},
            "Jena":{"configuredLevel":null,"effectiveLevel":"DEBUG"},
            "SPARQL":{"configuredLevel":"ERROR","effectiveLevel":"ERROR"},
            "audit":{"configuredLevel":"INFO","effectiveLevel":"INFO"},
            "com":{"configuredLevel":null,"effectiveLevel":"DEBUG"},
            "com.eccenca":{"configuredLevel":null,"effectiveLevel":"DEBUG"},
            "com.eccenca.elds":{"configuredLevel":null,"effectiveLevel":"DEBUG"},
            "com.eccenca.elds.backend":
              {"configuredLevel":"DEBUG","effectiveLevel":"DEBUG"},
            "com.eccenca.elds.backend.cache":
              {"configuredLevel":null,"effectiveLevel":"DEBUG"}
          }
        }
        
        
  • HTTP Status Code 401:

    • Access denied for the current user. The access token is invalid.
  • HTTP Status Code 403:

    • Access denied for the current user. Only root users can use this endpoint.
<!-- resource -->

Application loggers by name (/{loggerName})

Full URL: /actuator/loggers/{loggerName}

URI parameters:

  • loggerName, required:

    The name of the logger to manage.

    • type: (string)

Valid HTTP methods are:

GET

Display the configured logging level for the specified logger.

Response

The expected response:

  • HTTP Status Code 200:

    • application/json:

      • example:

        {"configuredLevel":"DEBUG","effectiveLevel":"DEBUG"}
        
        
  • HTTP Status Code 400:

    • The logging level couldn't be changed due to a malformed request. Refer to the response body for a detailed error description.
  • HTTP Status Code 401:

    • Access denied for the current user. The access token is invalid.
  • HTTP Status Code 403:

    • Access denied for the current user. Only root users can use this endpoint.

POST

Change the configured logging level for the specified logger.

Body

This method accepts the following body payloads:

  • application/json:

    • schema:

      {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties":
        {
          "configuredLevel":
          {
            "description": "The explicit logging level to be configured",
            "type": "string",
            "enum": ["TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL", "OFF", "null"]
          }
        },
        "required": ["configuredLevel"]
      }
      
      
    • example:

      {"configuredLevel":"TRACE"}
      
      
Response

The expected response:

  • HTTP Status Code 200:

    • The logging level was configured successfully.
  • HTTP Status Code 400:

    • The logging level couldn't be changed due to a malformed request. Refer to the response body for a detailed error description.
  • HTTP Status Code 401:

    • Access denied for the current user. The access token is invalid.
  • HTTP Status Code 403:

    • Access denied for the current user. Only root users can use this endpoint.
  • HTTP Status Code 415:

    • If no or a wrong Conent-Type header is given.
<!-- resources:end --> <!-- resources:end -->

Vocabulary Management (/api/vocab)

Beta - This api is subject to change in the next releases without further notice.

Lists all Vocabularies of the default endpoint.

<!-- resource -->

Vocabulary Management (/api/vocab)

Full URL: /api/vocab

Valid HTTP methods are:

GET

Query Parameters

This method accepts the following query parameters:

  • searchTerm:

    A full text search term

    • type: (string)
  • vocabGraph:

    The Vocabulary Catalog to query

    • type: (string)
  • limit:

    max number of results

    • type: (string)
  • offset:

    skip the first results

    • type: (string)
  • orderByCol:

    by which colum the list should be sorted

    • type: (string)
  • orderBy:

    Either ASC ord DESC

    • type: (string)
Response

The expected response:

  • HTTP Status Code 200:

    • application/json:

      • example:

        {
          "totalCount": "1",
          "vocabularies": [
            {"iri": "http://exmaple.com/myvocab", ....}
        
          ]
        }
        
        
<!-- resources:end -->