OpenSKOS logo OpenSKOS: Simple Knowledge Organization System Repository

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.

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":
/ccr/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

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

  1. <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:skos="http://www.w3.org/2004/02/skos/core#">
  2.   <rdf:Description rdf:about="http://data.beeldengeluid.nl/gtaa/28586">
  3.     <rdf:type rdf:resource="http://www.w3.org/2004/02/skos/core#Concept"/>
  4.     <skos:prefLabel xml:lang="nl">doodstraf</skos:prefLabel>
  5.     <skos:inScheme rdf:resource="http://data.beeldengeluid.nl/gtaa/Onderwerpen"/>
  6.     <skos:broader rdf:resource="http://data.beeldengeluid.nl/gtaa/24842"/>
  7.     <skos:related rdf:resource="http://data.beeldengeluid.nl/gtaa/25652"/>
  8.     <skos:related rdf:resource="http://data.beeldengeluid.nl/gtaa/24957"/>
  9.     <skos:altLabel xml:lang="nl">kruisigingen</skos:altLabel>
  10.     <skos:broader rdf:resource="http://data.beeldengeluid.nl/gtaa/27731"/>
  11.     <skos:related rdf:resource="http://data.beeldengeluid.nl/gtaa/28109"/>
  12.     <skos:inScheme rdf:resource="http://data.beeldengeluid.nl/gtaa/GTAA"/>
  13.     <skos:notation>28586</skos:notation>
  14.   </rdf:Description>
  15. </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:

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

  1. <rdf:RDF 
  2.   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
  3.   xmlns:openskos="http://openskos.org/xmlns#"
  4.   xmlns:skos="http://www.w3.org/2004/02/skos/core#"
  5.   openskos:tenant="beg" openskos:collection="gtaa" openskos:key="your-api-key">
  6.   <rdf:Description rdf:about="http://data.beeldengeluid.nl/gtaa/28586">
  7.     <rdf:type rdf:resource="http://www.w3.org/2004/02/skos/core#Concept"/>
  8.     <skos:prefLabel xml:lang="nl">doodstraf</skos:prefLabel>
  9.     <skos:inScheme rdf:resource="http://data.beeldengeluid.nl/gtaa/Onderwerpen"/>
  10.     <skos:broader rdf:resource="http://data.beeldengeluid.nl/gtaa/24842"/>
  11.     <skos:related rdf:resource="http://data.beeldengeluid.nl/gtaa/25652"/>
  12.     <skos:related rdf:resource="http://data.beeldengeluid.nl/gtaa/24957"/>
  13.     <skos:altLabel xml:lang="nl">kruisigingen</skos:altLabel>
  14.     <skos:broader rdf:resource="http://data.beeldengeluid.nl/gtaa/27731"/>
  15.     <skos:related rdf:resource="http://data.beeldengeluid.nl/gtaa/28109"/>
  16.     <skos:inScheme rdf:resource="http://data.beeldengeluid.nl/gtaa/GTAA"/>
  17.     <skos:notation>28586</skos:notation>
  18.   </rdf:Description>
  19. </rdf:RDF>

Example: create a new SKOS concept with Zend Framework's HTTP Client

  1. $client = new Zend_Http_Client('http://concepts.clarin.eu/api/concept', array(
  2.     'maxredirects' => 0,
  3.     'timeout'      => 30));
  4. $response = $client
  5.     ->setEncType('text/xml')
  6.     ->setRawData($xml)
  7.     ->setParameterGet('tenant', 'beg')
  8.     ->setParameterGet('collection', 'gtaa')
  9.     ->setParameterGet('key', 'your-valid-api-key')
  10.     ->request('POST');
  11. if ($response->isSuccessful()) {
  12.     echo 'Concept created';
  13. } else {
  14. 	echo 'Failed to create concept: ' . $response->getHeader('X-Error-Msg');
  15. }

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.

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

  1. $client = new Zend_Http_Client('http://concepts.clarin.eu/api/concept', array(
  2.     'maxredirects' => 0,
  3.     'timeout'      => 30));
  4. $response = $client
  5.     ->setEncType('text/xml')
  6.     ->setRawData($xml)
  7.     ->setParameterGet('tenant', 'beg')
  8.     ->setParameterGet('collection', 'gtaa')
  9.     ->setParameterGet('key', 'your-valid-api-key')
  10.     ->request('PUT');
  11. if ($response->isSuccessful()) {
  12.     echo 'Concept created';
  13. } else {
  14.     echo 'Failed to create concept: ' . $response->getHeader('X-Error-Msg');
  15. }
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

  1. $client = new Zend_Http_Client('http://concepts.clarin.eu/api/concept', array(
  2.     'maxredirects' => 0,
  3.     'timeout'      => 30));
  4. $response = $client
  5.     ->setParameterGet('tenant', 'beg')
  6.     ->setParameterGet('collection', 'gtaa')
  7.     ->setParameterGet('key', 'your-valid-api-key')
  8.     ->setParameterGet('id', 'http://data.beeldengeluid.nl/gtaa/28586')
  9.     ->request('DELETE');
  10. if ($response->isSuccessful()) {
  11.     echo 'Concept deleted';
  12. } else {
  13.     echo 'Failed to delete concept: ' . $response->getHeader('X-Error-Msg');
  14. }

Institutions

Collections