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/jsonExample 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.
- 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.
-
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.
- 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.
-
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.
- 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.
-
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