Service Documentation
This library takes your skosproviders and makes them available as REST services. The pyramid_skosprovider serves JSON as a REST service so it can be used easily inside a AJAX webbrowser call or by an external program.
The following API can be used by clients:
- GET /uris
Find more information on a certain URI. This can map to eiter a concept, collection or conceptscheme that is known by the current SKOS registry.
Example request:
GET /uris?uri=urn:x-skosprovider:trees HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "id": "TREES", "uri": "urn:x-skosprovider:trees", "type": "concept_scheme" }
Example request:
GET /uris/?uri=http://python.com/trees/larch HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "id": "1", "uri": "http://python.com/trees/larch", "type": "concept", "concept_scheme": { "id": "TREES", "uri": "urn:x-skosprovider:trees" } }
- Query Parameters:
uri – The URI to search for.
- Status Codes:
200 OK – The URI maps to something known by pyramid_skosprovider, either a conceptscheme, a concept or collection.
404 Not Found – The URI can’t be found by pyramid_skosprovider.
- GET /c
Search for concepts or collections, no matter what scheme they’re a part of.
Although it is possible to search a single conceptscheme with just this endpoint, for performance reasons it is advised to use
GET /conceptschemes/{scheme_id}/c
.Example request:
GET /c HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Range: items 0-2/232 Content-Type: application/json; charset=UTF-8 [ { "id": "1", "uri": "urn:x-skosprovider:TREES:1", "type": "concept", "label": "De Lariks" }, { "id": "2", "uri": "urn:x-skosprovider:TREES:2", "type": "concept", "label": "De Paardekastanje" }, { "id": 3, "uri": "urn:x-skosprovider:TREES:3", "type": "collection", "label": "Bomen per soort" } ]
Example request:
GET /c?type=concept&providers.subject=external&sort=uri HTTP/1.1 Host: localhost:6543 Accept: application/json
- Query Parameters:
type – Define if you want to show concepts or collections. Leave blank to show both.
mode – Allows for special processing mode for dijitFilteringSelect. Makes it possible to use wildcards in the label parameter.
label – Shows all concepts and collections that have this search string in one of their labels.
language – Returns the label with the corresponding language-tag if present. If the language is not present for this concept/collection, it falls back to 1) the default language of the provider. 2) ‘en’ 3) any label. Eg.
?language=nl
to show the dutch labels of the concepts/collections.sort – Define if you want to sort the results by a given field. Otherwise items are returned in an indeterminate order. Prefix with ‘+’ to sort ascending, ‘-’ to sort descending. eg.
?sort=-label
to sort all results descending by label.match – A URI for an external concept. Searches if any of the providers have a matching concept.
match_type – A type of match: exact, close, related, broader, narrower. Only used if a match URI is present as well.
providers.ids – A comma separated list of concept scheme id’s. The query will only be passed to the providers with these id’s. eg.
?providers.ids=TREES, PARROTS
will only list concepts from these two providers.providers.subject – A subject can be registered with a skosprovider in the registry. Adding this search parameter means that the query will only be passed on to providers that have been tagged with this subject. Eg.
?providers.subject=external
to only query the providers that have been marked with the subject external.
- Request Headers:
Range – Can be used to request a certain set of results. eg.
items=0-24
requests the first 25 results.
- Response Headers:
Content-Range – Tells the client what set of results is being returned eg.
items=0-24/306
means the first 25 out of 306 results are being returned.
- Status Codes:
200 OK – The concepts in this conceptscheme were found.
- GET /conceptschemes
Get all registered conceptschemes.
Example request:
GET /conceptschemes HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Mon, 14 Apr 2014 14:42:34 GMT [ { "id": "TREES", "uri": "urn:x-skosprovider:trees", "label": "Different types of trees." } ]
- Status Codes:
200 OK – The list of conceptschemes was found.
- GET /conceptschemes/{scheme_id}
Get information about a concept scheme.
Example request:
GET /conceptschemes/TREES HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Length: 15 Content-Type: application/json; charset=UTF-8 Date: Mon, 14 Apr 2014 14:45:37 GMT Server: waitress { "id": "TREES", "uri": "urn:x-skosprovider:trees", "label": "Different types of trees.", "labels": [ {"type": "prefLabel", "language": "en", "label": "Different types of trees."}, {"type": "prefLabel", "language": "nl", "label": "Verschillende soorten bomen."} ] }
Example request:
-.. sourcecode:: http
GET /conceptschemes/PLANTS HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 404 Not Found Content-Length: 775 Content-Type: text/html; charset=UTF-8 Date: Tue, 15 Apr 2014 20:32:52 GMT Server: waitress
- Status Codes:
200 OK – The conceptscheme was found.
404 Not Found – The conceptscheme was not found.
- GET /conceptschemes/{scheme_id}/topconcepts
Get all top concepts in a certain conceptscheme. These are all the concepts in the conceptscheme that have no broader concept.
Example request:
GET /conceptschemes/TREES/topconcepts HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Mon, 14 Apr 2014 14:47:33 GMT Server: waitress [ { "id": "1", "uri": "urn:x-skosprovider:TREES:1", "type": "concept", "label": "De Lariks" }, { "id": "2", "uri": "urn:x-skosprovider:TREES:2", "type": "concept", "label": "De Paardekastanje" } ]
- Query Parameters:
language – Returns the label with the corresponding language-tag if present. If the language is not present for this concept/collection, it falls back to 1) the default language of the provider. 2) ‘en’ 3) any label. Eg.
?language=nl
to show the dutch labels of the concepts/collections.
- Status Codes:
200 OK – The topconcepts in this conceptscheme were found.
404 Not Found – The conceptscheme was not found.
- GET /conceptschemes/{scheme_id}/displaytop
Get the top of a display hierarchy. Depending on the underlying provider this will be a list of Concepts and Collections.
Example request:
GET /conceptschemes/TREES/displaytop HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Mon, 14 Apr 2014 14:47:33 GMT Server: waitress [ { "id": "1", "uri": "urn:x-skosprovider:TREES:1", "type": "concept", "label": "De Lariks" }, { "id": "2", "uri": "urn:x-skosprovider:TREES:2", "type": "concept", "label": "De Paardekastanje" } ]
- Query Parameters:
language – Returns the label with the corresponding language-tag if present. If the language is not present for this concept/collection, it falls back to 1) the default language of the provider. 2) ‘en’ 3) any label. Eg.
?language=nl
to show the dutch labels of the concepts/collections.
- Status Codes:
200 OK – The concepts and collections were found.
404 Not Found – The conceptscheme was not found.
- GET /conceptschemes/{scheme_id}/c
Search for concepts or collections in a scheme.
Example request:
GET /conceptschemes/TREES/c HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Length: 117 Content-Range: items 0-2/3 Content-Type: application/json; charset=UTF-8 Date: Mon, 14 Apr 2014 14:47:33 GMT Server: waitress [ { "id": "1", "uri": "urn:x-skosprovider:TREES:1", "type": "concept", "label": "De Lariks" }, { "id": "2", "uri": "urn:x-skosprovider:TREES:2", "type": "concept", "label": "De Paardekastanje" }, { "id": 3, "uri": "urn:x-skosprovider:TREES:3", "type": "collection", "label": "Bomen per soort" } ]
Example request:
GET /conceptschemes/PLANTS/c HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 404 Not Found Content-Length: 775 Content-Type: text/html; charset=UTF-8 Date: Tue, 15 Apr 2014 20:32:52 GMT Server: waitress
- Query Parameters:
type – Define if you want to show concepts or collections. Leave blank to show both.
mode – Allows for special processing mode for dijitFilteringSelect. Makes it possible to use wildcards in the label parameter.
label – Shows all concepts and collections that have this search string in one of their labels.
collection – Get information about the content of a collection. Expects to be passed an id of a collection in this scheme. Will restrict the search to concepts or collections that are a member of this collection or a narrower concept of a member.
match – A URI for an external concept. Searches if any of the providers have a matching concept.
match_type – A type of match: exact, close, related, broader, narrower. Only used if a match URI is present as well.
language – Returns the label with the corresponding language-tag if present. If the language is not present for this concept/collection, it falls back to 1) the default language of the provider. 2) ‘en’ 3) any label. Eg.
?language=nl
to show the dutch labels of the concepts/collections.sort – Define if you want to sort the results by a given field. Otherwise items are returned in an indeterminate order. Prefix with ‘+’ to sort ascending, ‘-’ to sort descending. eg.
?sort=-label
to sort all results descending by label.
- Request Headers:
Range – Can be used to request a certain set of results. eg.
items=0-24
requests the first 25 results.
- Response Headers:
Content-Range – Tells the client was set of results is being returned eg.
items=0-24/306
means the first 25 out of 306 results are being returned.
- Status Codes:
200 OK – The concepts in this conceptscheme were found.
404 Not Found – The conceptscheme was not found.
- GET /conceptschemes/{scheme_id}/c/{c_id}
Get information about a concept or collection.
Example request:
GET /conceptschemes/TREES/c/1 HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Mon, 14 Apr 2014 14:49:27 GMT Server: waitress { "broader": [], "narrower": [], "notes": [ {"note": "A type of tree.", "type": "definition", "language": "en"} ], "labels": [ {"type": "prefLabel", "language": "en", "label": "The Larch"}, {"type": "prefLabel", "language": "nl", "label": "De Lariks"} ], "type": "concept", "id": "1", "uri": "urn:x-skosprovider:TREES:1", "related": [], "label": "The Larch", "matches": { "close": [ "http://id.python.org/different/types/of/trees/nr/1/the/larch" ] }, "concept_scheme": { "uri": "urn:x-foo:bar" } }
Example request:
GET /conceptschemes/TREES/c/4 HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 404 Not Found Content-Length: 775 Content-Type: text/html; charset=UTF-8 Date: Tue, 15 Apr 2014 20:06:12 GMT Server: waitress
- Status Codes:
200 OK – The concept was found in the conceptscheme.
404 Not Found – The concept was not found in the conceptscheme or the conceptscheme was not found.
- GET /conceptschemes/{scheme_id}/c/{c_id}/displaychildren
Get a list of Collections and Concepts that should be displayed as children of this Concept or Collection.
Example request:
GET /conceptschemes/TREES/c/3/displaychildren HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Mon, 14 Apr 2014 14:49:27 GMT Server: waitress [ { "id": "1", "uri": "urn:x-skosprovider:TREES:1", "type": "concept", "label": "De Lariks" }, { "id": "2", "uri": "urn:x-skosprovider:TREES:2", "type": "concept", "label": "De Paardekastanje" } ]
- Query Parameters:
language – Returns the label with the corresponding language-tag if present. If the language is not present for this concept/collection, it falls back to 1) the default language of the provider. 2) ‘en’ 3) any label. Eg.
?language=nl
to show the dutch labels of the concepts/collections.
- Status Codes:
200 OK – The concept was found in the conceptscheme.
404 Not Found – The concept was not found in the conceptscheme or the conceptscheme was not found.
- GET /conceptschemes/{scheme_id}/c/{c_id}/expand
Expand a concept or collection to all it’s narrower concepts.
This method should recurse and also return narrower concepts of narrower concepts.
If the id passed belongs to a
skosprovider.skos.Concept
, the id of the concept itself should be include in the return value.If the id passed belongs to a
skosprovider.skos.Collection
, the id of the collection itself must not be present in the return value In this case the return value includes all the member concepts and their narrower concepts.- Returns A list of id’s or
HTTPNotFound
if the concept or collection doesn’t exist.
Example request:
GET /conceptschemes/TREES/c/3/expand HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Mon, 14 Apr 2014 14:49:27 GMT Server: waitress [1 , 2]
- Status Codes:
200 OK – The concept/collection was found in the conceptscheme.
404 Not Found – The concept/collection was not found in the conceptscheme or the conceptscheme was not found.
- Returns A list of id’s or