Welcome to the OpenSKOS API
About the OpenSKOS API
The OpenSKOS API is a RESTful webservice.
Examples
Autocomplete
The autocomplete API is a simplified version of the Find concepts API. You can use the autocomplete API in your projects, for example with as Javascript based autocompete field.
-
Get all lexical labels in JSON format, with a word in one of the lexical labels starting with "dood": /api/autocomplete/dood
This method returns all labels, including hiddenLabels and altLabels. This means it is possible that the service returns labels that do not match your pattern.
-
Get only lexical labels with languagecode "nl" in JSON format, with a word in one of the lexical labels starting with "dood": ?lang=nl /api/autocomplete/dood?lang=nl
-
Get all lexical labels in JSON format, with a word in one in the prefLabels starting with "dood": /api/autocomplete/dood?searchLabel=prefLabel
-
Get only prefLabels in JSON format, with a word in one in the labels starting with "dood": /api/autocomplete/dood?returnLabel=prefLabel
Once the user selects a label from the autocomplete list, you have to lookup the matching Concept.
You can do this by querying the find API with the selected label, for example if the user selects the label "Dantons Dood":
/api/find-concepts?q=prefLabel:"Dood Paard"&fl=uri
Please note: in the second call to the find API, it's possible the API returns multiple concepts. You should implement methods to handle this!
Find concepts
-
Find concepts that have a lexical label that matches the word "dood":
- in XML-RDF format: /api/find-concepts?q=dood
- in JSON format: /api/find-concepts?q=dood&format=json
- in JSONP format: /api/find-concepts?q=dood&format=jsonp&callback=myCallback_1234
-
Fetch a single concept:
- by URI: /api/find-concepts?id=http://data.beeldengeluid.nl/gtaa/215866
- by UUID: /api/find-concepts/0a39cbfc-a491-75f8-60b2-6b50418e299d
- by UUID in XML-RDF format: /api/find-concepts/0a39cbfc-a491-75f8-60b2-6b50418e299d.rdf
-
Advanced queries:
-
Search for concepts with specific status "approved":
/api/find-concepts?q=status:approved
All possible statuses are:candidate A newly added concept approved Candidate that was inspected and approved redirected Proposed concept was found to be better represented by another concept. The redirected concept will be maintained for convenience and will contain a forward note to the target concept. not_compliant Concept is not compliant with the GTAA standard, but is maintained for convenience of the creator. It can become obsolete when no longer necessary. rejected Substandard quality obsolete This concept is no longer necessary, may be succeeded by another concept. deleted All concept metadata is deleted. - Search for concepts in altLabels, in a case-sensitive way, matching the word "kruisigingen": /api/find-concepts?q=altLabel:kruisigingen
- Search for concepts in prefLabels in Dutch, in a case-insensitive way, matching the word "doodstraf": /api/find-concepts?q=prefLabelText@nl:doodstraf
- Search for concepts in altLabels, in a case-insensitive way, matching a word starting with "kr*": /api/find-concepts?q=altLabelText:kr*
- Search for concepts that have a notation value: /api/find-concepts?q=notation:[* TO *]
- Search for concepts that have a scopeNote value, returning only the uri and prefLabels and scopeNotes in dutch: /api/find-concepts?q=scopeNote:[* TO *]&fl=uri,scopeNote@nl,prefLabel@nl
- Count concepts that match the query "washington": /api/find-concepts?q=washington&rows=0
-
Sort results on particular field "prefLabelSort asc":
/api/find-concepts?q=washington&rows=0&sort=prefLabelSort asc
All possible sort fields:prefLabelSort prefLabelSort@{lang} notationSort
You can query for concepts using a valid query according to the Apache Lucene - Query Parser Syntax All classes of the SKOS vocabulary are supported. Classes can be search in a case-sensitive or case-insenitive way. Supported classes can be search limited to specific language codes. If You're Familiar with Apache Solr you can have lok at our Solr Schema.
-
Search for concepts with specific status "approved":
/api/find-concepts?q=status:approved
Create/Retrieve/Update/Delete Concepts
The OpenSKOS API provides a complete CRUD API through RESTful HTTP calls. All actions except the Retrieve action require a valid API key.
Example Concept in RDF-XML
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:skos="http://www.w3.org/2004/02/skos/core#"> <rdf:Description rdf:about="http://data.beeldengeluid.nl/gtaa/28586"> <rdf:type rdf:resource="http://www.w3.org/2004/02/skos/core#Concept"/> <skos:prefLabel xml:lang="nl">doodstraf</skos:prefLabel> <skos:inScheme rdf:resource="http://data.beeldengeluid.nl/gtaa/Onderwerpen"/> <skos:broader rdf:resource="http://data.beeldengeluid.nl/gtaa/24842"/> <skos:related rdf:resource="http://data.beeldengeluid.nl/gtaa/25652"/> <skos:related rdf:resource="http://data.beeldengeluid.nl/gtaa/24957"/> <skos:altLabel xml:lang="nl">kruisigingen</skos:altLabel> <skos:broader rdf:resource="http://data.beeldengeluid.nl/gtaa/27731"/> <skos:related rdf:resource="http://data.beeldengeluid.nl/gtaa/28109"/> <skos:inScheme rdf:resource="http://data.beeldengeluid.nl/gtaa/GTAA"/> <skos:notation>28586</skos:notation> </rdf:Description> </rdf:RDF>
Create Concepts
You can create a Concept by sending a POST request with a valid RDF XML document and some extra required parameters:
- tenant The institute code for your institute in the OpenSKOS portal
- collection The collection code for the collection the concept must be put in
- key A valid API key
-
autoGenerateIdentifiers
If set to true (any of "1", "true", "on" and "yes") the concept notation and uri (rdf:about) will be automatically generated.
If notation and/or uri exists in the xml and autoGenerateIdentifiers is true - an error will be thrown.
If set to false - the xml must contain both notation and uri (rdf:about). The uri must be based on notation (must contain the notation).
For your convenience, it is also possible to send the tenant, collection and key in the XML document, by setting the appropriate attributes in the openskos namespace.
Example Concept in RDF-XML, with tenant, collection and key embeded
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:openskos="http://openskos.org/xmlns#" xmlns:skos="http://www.w3.org/2004/02/skos/core#" openskos:tenant="beg" openskos:collection="gtaa" openskos:key="your-api-key"> <rdf:Description rdf:about="http://data.beeldengeluid.nl/gtaa/28586"> <rdf:type rdf:resource="http://www.w3.org/2004/02/skos/core#Concept"/> <skos:prefLabel xml:lang="nl">doodstraf</skos:prefLabel> <skos:inScheme rdf:resource="http://data.beeldengeluid.nl/gtaa/Onderwerpen"/> <skos:broader rdf:resource="http://data.beeldengeluid.nl/gtaa/24842"/> <skos:related rdf:resource="http://data.beeldengeluid.nl/gtaa/25652"/> <skos:related rdf:resource="http://data.beeldengeluid.nl/gtaa/24957"/> <skos:altLabel xml:lang="nl">kruisigingen</skos:altLabel> <skos:broader rdf:resource="http://data.beeldengeluid.nl/gtaa/27731"/> <skos:related rdf:resource="http://data.beeldengeluid.nl/gtaa/28109"/> <skos:inScheme rdf:resource="http://data.beeldengeluid.nl/gtaa/GTAA"/> <skos:notation>28586</skos:notation> </rdf:Description> </rdf:RDF>
Example: create a new SKOS concept with Zend Framework's HTTP Client
'maxredirects' => 0, 'timeout' => 30)); $response = $client ->setEncType('text/xml') ->setRawData($xml) ->setParameterGet('tenant', 'beg') ->setParameterGet('collection', 'gtaa') ->setParameterGet('key', 'your-valid-api-key') ->setParameterGet('autoGenerateIdentifiers', true) ->request('POST'); if ($response->isSuccessful()) { echo 'Concept created'; } else { }
You will get an error with the appropriate HTTP Status code. Errors will occur if a concept already exists, invalid XML or missing/non-existing collection/tenant and/or api-key
Retrieve Concepts
You can retrieve a concept by sending a GET request with a valid identifier.
-
Retrieve the concept "doodstraf" by it's UUID
- in RDF: /api/concept/82c2614c-3859-ed11-4e55-e993c06fd9fe.rdf
- in HTML: /api/concept/82c2614c-3859-ed11-4e55-e993c06fd9fe.html
- in JSON: /api/concept/82c2614c-3859-ed11-4e55-e993c06fd9fe.json
- in JSONP: /api/concept/82c2614c-3859-ed11-4e55-e993c06fd9fe.jsonp?callback=myCallback_1234
Retrieve the concept "doodstraf" by it's URI
- in RDF: /api/concept?id=http://data.beeldengeluid.nl/gtaa/28586
- in HTML: /api/concept?id=http://data.beeldengeluid.nl/gtaa/28586&format=html
- in JSON: /api/concept?id=http://data.beeldengeluid.nl/gtaa/28586&format=json
- in JSONP: /api/concept?id=http://data.beeldengeluid.nl/gtaa/28586&format=jsonp&callback=myCallback_1234
Update Concepts
The Update action works almost the same as the Create action, but by sending a PUT request with an existing Concept identifier.
Example: update an existing SKOS concept with Zend Framework's HTTP Client
'maxredirects' => 0, 'timeout' => 30)); $response = $client ->setEncType('text/xml') ->setRawData($xml) ->setParameterGet('tenant', 'beg') ->setParameterGet('collection', 'gtaa') ->setParameterGet('key', 'your-valid-api-key') ->request('PUT'); if ($response->isSuccessful()) { echo 'Concept created'; } else { }
Delete Concepts
By sending a DELETE request to the API with a valid, existing identifier, a Concept will be deleteded from the system.
Example: deleting an existing SKOS concept with Zend Framework's HTTP Client
'maxredirects' => 0, 'timeout' => 30)); $response = $client ->setParameterGet('tenant', 'beg') ->setParameterGet('collection', 'gtaa') ->setParameterGet('key', 'your-valid-api-key') ->setParameterGet('id', 'http://data.beeldengeluid.nl/gtaa/28586') ->request('DELETE'); if ($response->isSuccessful()) { echo 'Concept deleted'; } else { }
Institutions
- Fetch all Institutions in this repository
- in RDF: /api/institutions
- in JSON: /api/institutions?format=json
- in JSONP: /api/institutions?format=jsonp&callback=myCallback_1234
- in HTML: /api/institutions?format=html
- Fetch a single Institute from this repository
- in RDF: /api/institutions/beg
- in JSON: /api/institutions/beg.json
- in JSONP: /api/institutions/beg.jsonp?callback=myCallback_1234
- in HTML: /api/institutions/beg.html
Collections
- Fetch all Collections in this repository
- in RDF: /api/collections
- in JSON: /api/collections?format=json
- in JSONP: /api/collections?format=jsonp&callback=myCallback_1234
- in HTML: /api/collections?format=html
- Fetch a single Institute from this repository
- in RDF: /api/collections/beg:gtaa
- in JSON: /api/collections/beg:gtaa.json
- in JSONP: /api/collections/beg:gtaa.jsonp?callback=myCallback_1234
- in HTML: /api/collections/beg:gtaa.html