Note for smartphone users

Dear SKOS Shuttle API interested user,

this API specification page is kept as simple as possible for fluent reading. However, the inherent complexity to show in a structured way all API options forces a minimum screen width of 990px to show properly. For this reason, Semweb does not recommend to view this specification inside a Smartphone. Please consider viewing it on a device with a screen width of at least 990px - thank you.

SKOS Shuttle API is available for selections and update operations.



Security considerations

The API service is exclusively provided upon transport layer security with TLS 1.2
The API service needs the "api" right from SKOS Shuttle User Management (see tutorials).
The service must be authenticated against a valid SKOS Shuttle user.
In order for the called operation to be executed, the api user needs the corresponding (role) groups and rights for that operation.
Every api access is logged and historized.

Output formats

The API delivers results per default in JSON format. Further formats are available.


JSON:
/GET parameter: format=json
YAML:
/GET parameter: format=yaml
XML:
/GET parameter: format=xml

Language tags

Langage tags like "en", "fr", ... are a short form for the corresponding language which is stored in the RDF data with every label.

With SKOS Shuttle API you can restrict which labels (in which tags) should be returned with the results.

Use /GET parameter: langs=en{,fr,it,...}

Per default the API returns labels in all languages.

Example:


Labels in all languages:
Omit this parameter
Labels only in English:
/GET parameter: langs=en
Labels only in English or French:
/GET parameter: langs=en,fr

Namespaces

Namespaces can be forced to be returned either in short form or in full form.

Per default Namespaces are returned in short form.

Return namespaces in short form:
/GET parameter: ns=short or omit parameter
Return namespaces in full form /GET parameter:
/GET parameter: ns=full

RDF format on download/upload

RDF export / import operation support the following formats

Per default the used format is RDFXML

N3:
/GET parameter: rdfformat=N3
NTRIPLES:
/GET parameter: rdfformat=NTRIPLES
NQUADS:
/GET parameter: rdfformat=NQUADS
RDFXML:
/GET parameter: rdfformat=RDFXML or omit parameter
TRIG:
/GET parameter: rdfformat=TRIG
TURTLE:
/GET parameter: rdfformat=TURTLE

Additional RDF safe cheks

Additional RDF (SPARQL) update checks are performed to ensure, the updates coming from the API requests are effectevely stored. Every update is performed using SPARQL-UPDATE queries. The latter does not quit update operations with a precise statistic of what was changed by that queries. SKOS Shuttle API can additionally query the repository, whether the corresponding statements (RDF triples) where effectively modified by the action you specified on your API call.

Per default RDF save check is OFF.

Activate this check using:
/GET parameter: safe=true

POST vs GET data

Wherever possible the API uses /GET requests. Even if the request specifies an update. For those cases where additional data is required - like for example some RDF content - the API uses /POST raw body content with additional query string parameters).



Thesaurus operations have the following generic syntax:

/thesaurus/PTHENAME/action/PARAMETERS

Where:

PTHENAME: is the project name for a SKOS Shuttle thesaurus
PARAMETERS: a sequence of querystring parameters without initial "?"



Management operations have the following generic syntax:

/mgnt/action/PARAMETERS

Where:

PARAMETERS: a sequence of querystring parameters without initial "?"



Thesaurus SELECT operations returns extracted RDF data from a SKOS Shuttle project.

conceptSchemes

/GET /thesaurus/PTHENAME/conceptSchemes/PARAMETERS

searchConcepts

/GET /thesaurus/PTHENAME/searchConcepts/PARAMETERS

REQUIRED PARAMETERS
Output format t|text=Text used to search for concepts - can contains also blanks or round parentheses () parenthesis)
ADDITIONAL PARAMETERS
Limit limit=a positive number (default 10) to limit SPARQL statement retrieval
Offset offset=a positive number (default 0) to shift SPARQL statement retrieval
Search in sin|searchin= pl | al | hl | rl | sd | dd | * - search for text in:
pl - skos:prefLabel, al - skos:altLabel, hl - skos:hiddenLabel, rl - rdfs:label, sd - skos:definition, dd - dc:description
Only predicates op|onlyp=p1,p2,p3 - select results containing only these comma separated predicates (short or full URIs)
Only literals ol|onlyliterals=true|false - search only in literals (default: true)
Counting count|countconcepts=true|false - executes also a count queries without limit to measure all fitting concepts (default: false)
GENERIC PARAMETERS
Example
REQUIRED PARAMETERS (none)
GENERIC PARAMETERS
Example
topConcepts

/GET /thesaurus/PTHENAME/topConcepts/PARAMETERS

REQUIRED PARAMETERS
Output format u|uri=SHORT or FULL URI of concept scheme
GENERIC PARAMETERS
Example
concepts

/GET /thesaurus/PTHENAME/concepts/PARAMETERS

REQUIRED PARAMETERS
URI's of several concepts u|uri={SHORT or FULL URI of concept}*
GENERIC PARAMETERS
Example
concept

/GET /thesaurus/PTHENAME/concept/PARAMETERS

REQUIRED PARAMETERS
URI of one concept u|uri=SHORT or FULL URI of concept
GENERIC PARAMETERS
Example
conceptSubtree

/GET /thesaurus/PTHENAME/conceptSubtree/PARAMETERS

REQUIRED PARAMETERS
URI of one concept u|uri=SHORT or FULL URI of concept
GENERIC PARAMETERS
Example
getdocmetadata

/GET /thesaurus/PTHENAME/getdocmetadata/PARAMETERS

REQUIRED PARAMETERS
URI of one document d|docuri=SHORT or FULL URI of concept
GENERIC PARAMETERS
Example
getdoc

/GET /thesaurus/PTHENAME/getdoc/PARAMETERS

REQUIRED PARAMETERS
URI of one document d|docuri=SHORT or FULL URI of concept
GENERIC PARAMETERS
Example
getlanguagetrack

/GET /thesaurus/PTHENAME/getlanguagetrack/PARAMETERS

OPTIONAL PARAMETERS
Example
broaders

/GET /thesaurus/PTHENAME/broaders/PARAMETERS

REQUIRED PARAMETERS
URI of one concept u|uri=SHORT or FULL URI of concept
GENERIC PARAMETERS
Example
narrowers

/GET /thesaurus/PTHENAME/narrowers/PARAMETERS

REQUIRED PARAMETERS
URI of one concept u|uri=SHORT or FULL URI of concept
GENERIC PARAMETERS
Example
related

/GET /thesaurus/PTHENAME/related/PARAMETERS

REQUIRED PARAMETERS
URI of one concept u|uri=SHORT or FULL URI of concept
GENERIC PARAMETERS
Example
entitytypes

/GET /thesaurus/PTHENAME/entitytypes/PARAMETERS

REQUIRED PARAMETERS
URI of one concept u|uri=SHORT or FULL URI of concept
GENERIC PARAMETERS
Example
namespaces

/GET /thesaurus/PTHENAME/namespaces/PARAMETERS

REQUIRED PARAMETERS (None)
URI of one concept u|uri=SHORT or FULL URI of concept
GENERIC PARAMETERS
Example
properties

/GET /thesaurus/PTHENAME/properties/PARAMETERS

REQUIRED PARAMETERS (None)
GENERIC PARAMETERS
Example
rdfexportsubtree

/GET /thesaurus/PTHENAME/rdfexportsubtree/PARAMETERS

REQUIRED PARAMETERS
URI of one Concept u|uri={SHORT or FULL URI of concept}
GENERIC PARAMETERS
Example
snapshot

/GET /thesaurus/PTHENAME/snapshot/

REQUIRED PARAMETERS (None)
GENERIC PARAMETERS (None)
Example



Thesaurus SELECT operations returns extracted RDF data from a SKOS Shuttle project.

addConceptScheme

/GET /thesaurus/PTHENAME/addConceptScheme/PARAMETERS

REQUIRED PARAMETERS
preferred Label for concept scheme pl|preflabel={text for preferred label}
Concept URI u|uri={Text}
OPTIONAL PARAMETERS
GENERIC PARAMETERS
Example
deleteConceptScheme

/GET /thesaurus/PTHENAME/deleteConceptScheme/PARAMETERS

REQUIRED PARAMETERS
Concept URI u|uri={Text}
GENERIC PARAMETERS
Example
addConcept

/GET /thesaurus/PTHENAME/addConcept/PARAMETERS

REQUIRED PARAMETERS
preferred Label for concept scheme pl|preflabel={text for preferred label}
Concept URI (specify a broader concept for the added concept) b|broaderuri={SHORT or FULL URI of broader concept}
If safe=true, SKOS Shuttle checks that this URI exists before creating the concept
OPTIONAL PARAMETERS
GENERIC PARAMETERS
Example
deleteConcept

/GET /thesaurus/PTHENAME/deleteConcept/PARAMETERS

REQUIRED PARAMETERS
preferred Label for concept scheme pl|preflabel={text for preferred label}
Concept URI u|uri={SHORT or FULL URI of concept}}
GENERIC PARAMETERS
Example
uploaddoc

/POST /thesaurus/PTHENAME/uploaddoc/PARAMETERS + RAW BODY PAYLOAD

REQUIRED PARAMETERS
Concept URI u|uri={SHORT or FULL URI of concept}}
Document URI d|docuri={SHORT or FULL URI of document - ADVICE: please use the pattern semwebo:doc/filename_extension to be compliant with SKOS Shuttle documents processing! }}
DOC meta data format df|docformat={filename extension for content as it were stored in a filename}}
DOC meta data title t|title={title of document}}
DOC description de|description={description of document}}
DOC meta data date FROM d1|datefrom={date (from) in format dd.mm.yyyy}}
OPTIONAL PARAMETERS
GENERIC PARAMETERS
Example
associatedoc

/GET /thesaurus/PTHENAME/associatedoc/PARAMETERS

REQUIRED PARAMETERS
Concept URI u|uri={SHORT or FULL URI of concept}}
Document URI d|docuri={SHORT or FULL URI of document}}
GENERIC PARAMETERS
Example
dissociatedoc

/GET /thesaurus/PTHENAME/dissociatedoc/PARAMETERS

REQUIRED PARAMETERS
Concept URI u|uri={SHORT or FULL URI of concept}}
Document URI d|docuri={SHORT or FULL URI of document}}
GENERIC PARAMETERS
Output format format=json|xml|yaml
Example
addLiteral

/GET /thesaurus/PTHENAME/addLiteral/PARAMETERS

REQUIRED PARAMETERS
Text for literal nt|text={text for literal}
Concept URI u|uri={SHORT or FULL URI of concept}}
Property of Literal sk|skosproperty={prefLabel|altLabel|hiddenLabel|definition|scopeNote}
GENERIC PARAMETERS
Example
updateLiteral

/GET /thesaurus/PTHENAME/updateLiteral/PARAMETERS

REQUIRED PARAMETERS
Current text of literal ct|currtext={text for literal}
New text of literal nt|newtext={text for literal}
Concept URI u|uri={SHORT or FULL URI of concept}}
Property of Literal sk|skosproperty={prefLabel|altLabel|hiddenLabel|definition|scopeNote}
OPTIONAL PARAMETERS
GENERIC PARAMETERS
Example
deleteLiteral

/GET /thesaurus/PTHENAME/deleteLiteral/PARAMETERS

REQUIRED PARAMETERS
Current text of literal t|text={text for literal}
Concept URI u|uri={SHORT or FULL URI of concept}}
Property of Literal sk|skosproperty={prefLabel|altLabel|hiddenLabel|definition|scopeNote}
OPTIONAL PARAMETERS
GENERIC PARAMETERS
Example
addRelation

/GET /thesaurus/PTHENAME/addRelation/PARAMETERS

REQUIRED PARAMETERS
URI of source concept u|source={SHORT or FULL URI of concept}}
URI of target concept v|target={SHORT or FULL URI of concept}}
SKOS relation sr|skosrelation={broader|narrower|related}
GENERIC PARAMETERS
Example
deleteRelation

/GET /thesaurus/PTHENAME/deleteRelation/PARAMETERS

REQUIRED PARAMETERS
URI of source concept u|source={SHORT or FULL URI of concept}}
URI of target concept v|target={SHORT or FULL URI of concept}}
SKOS relation sr|skosrelation={broader|narrower|related}
GENERIC PARAMETERS
Example
rdfimportsubtree

/POST /thesaurus/PTHENAME/rdfimportsubtree/PARAMETERS + RAW BODY PAYLOAD

REQUIRED PARAMETERS
URI of subtree root concept u|source={SHORT or FULL URI of concept}}
RDF Input format rdfformat=N3|NTRIPLES|NQUADS|RDFXML|TRIG|TURTLE
RDF content RDF content in POST raw body payload
GENERIC PARAMETERS
OPTIONAL PARAMETERS
Example
rdfimport

/POST /thesaurus/PTHENAME/rdfimport/PARAMETERS + RAW BODY PAYLOAD

REQUIRED PARAMETERS
RDF Input format rdfformat=N3|NTRIPLES|NQUADS|RDFXML|TRIG|TURTLE
RDF content RDF content in POST raw body payload
OPTIONAL PARAMETERS
GENERIC PARAMETERS
Example
sparql

/POST /thesaurus/PTHENAME/sparql/ + RAW BODY PAYLOAD

REQUIRED PARAMETERS
RDF content SPARQL query in POST raw body payload
query=select * {?s ?p ?o} limit 3
OPTIONAL PARAMETERS
GENERIC PARAMETERS
Example
sparqlupdate

/POST /thesaurus/PTHENAME/sparqlupdate/ + RAW BODY PAYLOAD

REQUIRED PARAMETERS
RDF content SPARQL-UPDATE query in POST raw body payload
OPTIONAL PARAMETERS
GENERIC PARAMETERS
Example
recoversnapshot

/POST /thesaurus/PTHENAME/recoversnapshot/ + RAW BODY PAYLOAD

REQUIRED PARAMETERS
RDF content RDFXML snapshot content in POST raw body payload
GENERIC PARAMETERS
Example



Management SELECT operations return extracted management data from a SKOS Shuttle project.

services

/GET /mgnt/services/PARAMETERS

REQUIRED PARAMETERS (None)
GENERIC PARAMETERS
Example
projects

/GET /mgnt/projects/PARAMETERS

REQUIRED PARAMETERS (None)
GENERIC PARAMETERS
Example
groups

/GET /mgnt/groups/PARAMETERS

REQUIRED PARAMETERS (None)
GENERIC PARAMETERS
Example
rights

/GET /mgnt/rights/PARAMETERS

REQUIRED PARAMETERS (None)
GENERIC PARAMETERS
Example
users

/GET /mgnt/users/PARAMETERS

REQUIRED PARAMETERS (None)
GENERIC PARAMETERS
Example
user

/GET /mgnt/user/PARAMETERS

REQUIRED PARAMETERS
Login name of user ul|userlogin={name used to login}*
GENERIC PARAMETERS
Example
rightsforgroup

/GET /mgnt/rightsforgroup/PARAMETERS

REQUIRED PARAMETERS
Group name gn|groupname={Group name}*
GENERIC PARAMETERS
Example
groupsandrightsforuser

/GET /mgnt/groupsandrightsforuser/PARAMETERS

REQUIRED PARAMETERS
Login name of user ul|userlogin={name used to login}*
GENERIC PARAMETERS
Example