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.
  • 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:
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.
  • 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.