CTS2-LE REST API: SPARQL Query: Unterschied zwischen den Versionen

Aus CTS2-LE
Zur Navigation springen Zur Suche springen
(added supported protocols)
 
K
 
(2 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt)
Zeile 1: Zeile 1:
−
The CTS2-LE REST API implements the [http://www.w3.org/TR/2013/REC-sparql11-protocol-20130321/ SPARQL 1.1 Protocol]. However, the implemented SPARQL Protocol is limited to the [http://www.w3.org/TR/2013/REC-sparql11-protocol-20130321/#query-operation HTTP Query Operation]. Furthermore, the [http://www.w3.org/TR/sparql11-http-rdf-update/ SPARQL 1.1 Graph Store HTTP Protocol] is supported by CTS2-LE.
+
CTS2-LE allows for SPARQL-SELECT queries within and across terminologies.
 +
 
 +
=== Operation ===
 +
* '''Path:''' /WebCts2LE/service/crud/sparql/select
 +
* '''Method:''' GET
 +
* '''Path Parameters:''' -
 +
* '''Query Parameters:'''
 +
** ''query'': SPARQL select-query string
 +
* '''returns: ''' query results according to https://www.w3.org/TR/rdf-sparql-XMLres/ but WITHOUT the head-element
 +
 
 +
=== Example Call ===
 +
<code>http://localhost:8080/WebCts2LE/service/crud/sparql/select?query=select%20?val%20where%20%7B%20?x%20:name%20?n.%20?x%20:designation%20?d.%20?d%20:designationRole%2</code>
 +
 
 +
for uncoded query
 +
<code>select ?val where { ?x :name ?n. ?x :designation ?d. ?d :designationRole 'PREFERRED'; :value ?val } limit 10</code>
 +
 
 +
===== Example Response Structure =====
 +
 
 +
<pre>
 +
<?xml version="1.0"?>
 +
<sparql xmlns="http://www.w3.org/2005/sparql-results#">
 +
  <results>
 +
    <result>
 +
      <binding name="val">
 +
        <literal>...</literal>
 +
      </binding>
 +
    </result>
 +
    ...
 +
  </results>
 +
</sparql>
 +
</pre>
 +
 
 +
<!-- shifted
 +
The CTS2-LE REST API implements the [http://www.w3.org/TR/2013/REC-sparql11-protocol-20130321/ SPARQL 1.1 Protocol], but is limited to the [http://www.w3.org/TR/2013/REC-sparql11-protocol-20130321/#query-operation HTTP Query] operation. Furthermore, the [http://www.w3.org/TR/sparql11-http-rdf-update/ SPARQL 1.1 Graph Store HTTP Protocol] is supported by CTS2-LE which is  restricted to [http://www.w3.org/TR/sparql11-http-rdf-update/#http-get HTTP GET] and [http://www.w3.org/TR/sparql11-http-rdf-update/#http-put HTTP PUT] operations.
 +
 
 +
== SPARQL 1.1 Protocol - HTTP Query Operation ==
 +
This REST call executes a given SPARQL query with CTS2-LE.
 +
 
 +
=== Operation Syntax for HTTP Request Method GET ===
 +
Clients must URL percent encode all parameters and include them as query parameter strings with the names given above [RFC3986]. HTTP query string parameters must be separated with the ampersand (&) character. Clients may include the query string parameters in any order. The HTTP request MUST NOT include a message body.
 +
 
 +
==== Signature ====
 +
GET /rest/sparql
 +
 
 +
==== Supported Parameters ====
 +
{| class="wikitable sortable"
 +
! Parameters !! Description
 +
|-
 +
| query || the SPARQL query string (exactly 1)
 +
|-
 +
| default-graph-uri || the default graph URIs (0 or more)
 +
|-
 +
| named-graph-uri || the named graph URIs (0 or more)
 +
|-
 +
|}
 +
 
 +
==== Returns ====
 +
* HTTP status code 200 for a successful query. The response body is in the [http://www.w3.org/TR/rdf-sparql-XMLres/ SPARQL Query Results XML Format].
 +
* HTTP status code 400 if the SPARQL query supplied in the request is not a legal sequence of characters in the language defined by the SPARQL grammar; or,
 +
* 500 if the service fails to execute the query. SPARQL Protocol services may also return a 500 response code if they refuse to execute a query. This response does not indicate whether the server may or may not process a subsequent, identical request or requests.
 +
 
 +
==== See also ====
 +
http://www.w3.org/TR/sparql11-protocol/#query-via-get
 +
 
 +
==== REST Call Syntax ====
 +
<pre style="white-space: pre-wrap;
 +
white-space: -moz-pre-wrap;
 +
white-space: -pre-wrap;
 +
white-space: -o-pre-wrap;
 +
word-wrap: break-word;">
 +
http://<host>/WebCts2LE/rest/sparql/?query=?query=SELECT%20%3Fpt%20%3Fl%20%3Fid%20%3Furi%20%0D%0AWHERE%20%7B%0D%0A%20%20%20%3Fx%20a%20%3AClassDescription%3B%0D%0A%20%20%20%20%20%20%3ApreferredTerm%20%3Fpt%3B%0D%0A%20%20%20%20%20%20%3Aname%20'DOC'.%0D%0A%0D%0A%20%20%20%3Fcs%20a%20%3ACodeSystemVersionCatalogEntry%3B%0D%0A%20%20%20%20%20%20%20%3Aentity%20%20%20%20%20%20%20%20%20%20%3Fx%3B%0D%0A%20%20%20%20%20%20%20%3AresourceID%20%20%20%20%20%20%3Fid%3B%0D%0A%20%20%20%20%20%20%20%3AaboutUri%20%20%20%20%20%20%20%20%3Furi%3B%0D%0A%20%20%20%20%20%20%20%3AdefaultLanguage%20%3Fl.%0D%0A%7D</pre>
 +
 
 +
=== Operation Syntax for HTTP Request Method POST ===
 +
Clients must include the SPARQL query string, unencoded, and nothing else as the message body of the request. Clients must set the content type header of the HTTP request to ''application/sparql-query''. Clients may include the optional ''default-graph-uri'' and ''named-graph-uri'' parameters as HTTP query string parameters in the request URI. Note that UTF-8 is the only valid charset here.
 +
 
 +
==== Signature ====
 +
POST /rest/sparql
 +
 
 +
==== Supported Parameters ====
 +
{| class="wikitable sortable"
 +
! Parameters !! Description
 +
|-
 +
| default-graph-uri || the default graph URIs (0 or more)
 +
|-
 +
| named-graph-uri || the named graph URIs (0 or more)
 +
|-
 +
|}
 +
 
 +
==== Returns ====
 +
* HTTP status code 200 for a successful query. The response body is in the [http://www.w3.org/TR/rdf-sparql-XMLres/ SPARQL Query Results XML Format].
 +
* HTTP status code 400 if the SPARQL query supplied in the request is not a legal sequence of characters in the language defined by the SPARQL grammar; or,
 +
* 500 if the service fails to execute the query. SPARQL Protocol services may also return a 500 response code if they refuse to execute a query. This response does not indicate whether the server may or may not process a subsequent, identical request or requests.
 +
 
 +
==== See also ====
 +
http://www.w3.org/TR/sparql11-protocol/#query-via-post-direct
 +
 
 +
==== REST Call Syntax ====
 +
<pre style="white-space: pre-wrap; white-space: -moz-pre-wrap; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: break-word;">
 +
POST rest/sparql/ HTTP/1.1
 +
Host: &lt;host&gt;
 +
User-agent: sparql-client/0.1
 +
Content-Type: application/sparql-query
 +
 
 +
SELECT ?pt ?l ?id ?uri
 +
WHERE {
 +
  ?x a :ClassDescription;
 +
      :preferredTerm ?pt;
 +
      :name 'DOC'.
 +
 
 +
  ?cs a :CodeSystemVersionCatalogEntry;
 +
      :entity          ?x;
 +
      :resourceID      ?id;
 +
      :aboutUri        ?uri;
 +
      :defaultLanguage ?l.
 +
}
 +
</pre>
 +
 
 +
=== Operation Syntax for HTTP Request Method POST (URL encoded) ===
 +
Clients must URL percent encode all parameters and include them as parameters within the request body via the ''application/x-www-form-urlencoded'' media type with the name given above. Parameters must be separated with the ampersand (&) character. Clients may include the parameters in any order. The content type header of the HTTP request must be set to ''application/x-www-form-urlencoded''.
 +
 
 +
==== Signature ====
 +
POST /rest/sparql
 +
 
 +
==== Supported Parameters ====
 +
{| class="wikitable sortable"
 +
! Parameters !! Description
 +
|-
 +
| query || the SPARQL query string (exactly 1)
 +
|-
 +
| default-graph-uri || the default graph URIs (0 or more)
 +
|-
 +
| named-graph-uri || the named graph URIs (0 or more)
 +
|-
 +
|}
 +
 
 +
==== Returns ====
 +
* HTTP status code 200 for a successful query. The response body is in the [http://www.w3.org/TR/rdf-sparql-XMLres/ SPARQL Query Results XML Format].
 +
* HTTP status code 400 if the SPARQL query supplied in the request is not a legal sequence of characters in the language defined by the SPARQL grammar; or,
 +
* 500 if the service fails to execute the query. SPARQL Protocol services may also return a 500 response code if they refuse to execute a query. This response does not indicate whether the server may or may not process a subsequent, identical request or requests.
 +
 
 +
==== See also ====
 +
http://www.w3.org/TR/sparql11-protocol/#query-via-post-urlencoded
 +
 
 +
==== REST Call Syntax ====
 +
<pre style="white-space: pre-wrap; white-space: -moz-pre-wrap; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: break-word;">
 +
POST rest/sparql/ HTTP/1.1
 +
Host: &lt;host&gt;
 +
User-agent: sparql-client/0.1
 +
Content-Type: application/x-www-form-urlencoded
 +
 
 +
query=SELECT%20%3Fpt%20%3Fl%20%3Fid%20%3Furi%20%0D%0AWHERE%20%7B%0D%0A%20%20%20%3Fx%20a%20%3AClassDescription%3B%0D%0A%20%20%20%20%20%20%3ApreferredTerm%20%3Fpt%3B%0D%0A%20%20%20%20%20%20%3Aname%20'DOC'.%0D%0A%0D%0A%20%20%20%3Fcs%20a%20%3ACodeSystemVersionCatalogEntry%3B%0D%0A%20%20%20%20%20%20%20%3Aentity%20%20%20%20%20%20%20%20%20%20%3Fx%3B%0D%0A%20%20%20%20%20%20%20%3AresourceID%20%20%20%20%20%20%3Fid%3B%0D%0A%20%20%20%20%20%20%20%3AaboutUri%20%20%20%20%20%20%20%20%3Furi%3B%0D%0A%20%20%20%20%20%20%20%3AdefaultLanguage%20%3Fl.%0D%0A%7D
 +
</pre>
 +
 
 +
 
 +
== SPARQL 1.1 Graph Store HTTP Protocol ==
 +
The following HTTP methods manage RDF graphs stored within CTS2-LE. See [http://www.w3.org/TR/sparql11-http-rdf-update/ SPARQL 1.1 Graph Store HTTP Protocol] for further information.
 +
 
 +
=== Operation Syntax for [http://www.w3.org/TR/sparql11-http-rdf-update/#http-get HTTP Request Method GET] ===
 +
* Returns status code (200) indicating the request succeeded normally.
 +
* Returns status code (400) indicating the request sent by the client was syntactically incorrect.
 +
* Returns Status code (406) indicating that the resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request.
 +
 
 +
=== Operation Syntax for [http://www.w3.org/TR/sparql11-http-rdf-update/#http-put HTTP Request Method PUT] ===
 +
* Returns status code (200) indicating the request succeeded normally.
 +
* Returns status code (400) indicating the request sent by the client was syntactically incorrect.
 +
* Returns status code (409) indicating that the request could not be completed due to a conflict with the current state of the resource.
 +
* Returns status code (500) indicating an error inside CTS2-LE which prevented it from fulfilling the request.
 +
 
 +
=== Operation Syntax for [http://www.w3.org/TR/sparql11-http-rdf-update/#http-delete HTTP Request Method DELETE] ===
 +
This HTTP method is not implemented. Thus, CTS2-LE returns status code (501) indicating CTS2-LE does not support the functionality needed to fulfill the request.
 +
 
 +
=== Operation Syntax for [http://www.w3.org/TR/sparql11-http-rdf-update/#http-post HTTP Request Method POST] ===
 +
This HTTP method is not implemented. Thus, CTS2-LE returns status code (501) indicating CTS2-LE does not support the functionality needed to fulfill the request.
 +
-->

Aktuelle Version vom 24. August 2016, 19:32 Uhr

CTS2-LE allows for SPARQL-SELECT queries within and across terminologies.

Operation

  • Path: /WebCts2LE/service/crud/sparql/select
  • Method: GET
  • Path Parameters: -
  • Query Parameters:
    • query: SPARQL select-query string
  • returns: query results according to https://www.w3.org/TR/rdf-sparql-XMLres/ but WITHOUT the head-element

Example Call

http://localhost:8080/WebCts2LE/service/crud/sparql/select?query=select%20?val%20where%20%7B%20?x%20:name%20?n.%20?x%20:designation%20?d.%20?d%20:designationRole%2

for uncoded query select ?val where { ?x :name ?n. ?x :designation ?d. ?d :designationRole 'PREFERRED'; :value ?val } limit 10

Example Response Structure
<?xml version="1.0"?>
<sparql xmlns="http://www.w3.org/2005/sparql-results#">
  <results>
    <result>
      <binding name="val">
        <literal>...</literal>
      </binding>
    </result>
    ...
  </results>
</sparql>


Abgerufen von „https://websites.fraunhofer.de/CTS2-LE/index.php?title=CTS2-LE_REST_API:_SPARQL_Query&oldid=476“