Services¶

Atramhasis can be used fully with a SOA. While we provide a public and and an administrator’s interface out of the box, you can also write your own client side code that interacts with the Atramhasis services, either for reading information or writing it.

While this chapter provides more narrative documentation on the services available, the most up to date version of the API can be accessed through the online API docs at the Flander Heritage Thesaurus or in your local version at /api_doc.

Pyramid_skosprovider¶

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:

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

Atramhasis¶

Concepts and collections¶

The main Atramhasis write services allow you to add concepts and collections, edit them and delete them.

POST /conceptschemes/{scheme_id}/c¶

Add a concept or collection to a conceptscheme. The response body will contain a representation of the concept or collection after is has been added to the conceptscheme.

Example request:

POST /conceptschemes/TREES/c HTTP/1.1
Host: demo.atramhasis.org
Accept: application/json
Content-Type: application/json

{
    "type": "concept",
    "broader": [],
    "narrower": [],
    "related": [],
    "labels": [
        {
            "type": "prefLabel",
            "language": "en",
            "label": "The Larch"
        }
    ],
    "notes": []
}

Example response:

HTTP/1.1 201 Created
Location: http://demo.atramhasis.org/conceptschemes/TREES/c/1
Content-Type: application/json

{
    "id": 1,
    "uri": "urn:x-atramhasis-demo:TREES:1",
    "type": "concept",
    "broader": [],
    "narrower": [],
    "related": [],
    "labels": [
        {
            "type": "prefLabel",
            "language": "en",
            "label": "The Larch"
        }
    ],
    "notes": []
}

Example request:

POST /conceptschemes/TAUNTS/c HTTP/1.1
Host: demo.atramhasis.org
Accept: application/json
Content-Type: application/json

{
    "type": "concept",
    "broader": [],
    "narrower": [],
    "related": [],
    "labels": [
        {
            "type": "tauntLabel",
            "language": "en-FR",
            "label": "Your mother was a Hamster!"
        }
    ],
    "notes": []
}

Example response:

HTTP/1.1 400 Bad Request
Location: http://demo.atramhasis.org/conceptschemes/TREES/c/1
Content-Type: application/json

{
    "errors": [
                {"labels": "Invalid labeltype."},
                {"labels": "Invalid language."}
              ],
    "message": "Concept could not be validated"
}

Parameters:

scheme_id – The identifier for a certain concept scheme.

Request Headers:

Accept – The response content type depends on this header. Currently only application/json is supported.

Response Headers:

Content-Type – This service currently always returns application/json
Location – The url where the newly added concept or collection can be found.

Status Codes:

201 Created – The concept or collection was added succesfully.
400 Bad Request – The concept or collection could not be added because the submitted json was invalid due to eg. validation errors.
404 Not Found – The conceptscheme scheme_id does not exist.
405 Method Not Allowed – The concept or collection could not be added because the conceptscheme scheme_id is a readonly conceptscheme.

PUT /conceptschemes/{scheme_id}/c/{c_id}¶

Edit the concept or collection with id c_id. The response body will contain a representation of the concept or collection after the modifications.

Example request:

PUT /conceptschemes/TREES/c/1 HTTP/1.1
Host: demo.atramhasis.org
Accept: application/json
Content-Type: application/json

{
    "type": "concept",
    "broader": [],
    "narrower": [],
    "related": [],
    "labels": [
        {
            "type": "prefLabel",
            "language": "en",
            "label": "The Larch"
        }, {
            "type": "prefLabel",
            "language": "nl",
            "label": "De Lariks"
        }
    ],
    "notes": []
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "uri": "urn:x-atramhasis-demo:TREES:1",
    "type": "concept",
    "broader": [],
    "narrower": [],
    "related": [],
    "labels": [
        {
            "type": "prefLabel",
            "language": "en",
            "label": "The Larch"
        }, {
            "type": "prefLabel",
            "language": "nl",
            "label": "De Lariks"
        }
    ],
    "notes": []
}

Parameters:

scheme_id – The identifier for a certain concept scheme.
c_id – The identifier for a certain concept or collection.

Request Headers:

Accept – The response content type depends on this header. Currently only application/json is supported.

Response Headers:

Content-Type – This service currently always returns application/json

Status Codes:

200 OK – The concept or collection was edited succesfully.
400 Bad Request – The concept or collection could not be edited because the submitted json was invalid due to eg. validation errors.
404 Not Found – The conceptscheme scheme_id or the concept or collection c_id does not exist.
405 Method Not Allowed – The concept or collection could not be edited because the conceptscheme scheme_id is a readonly conceptscheme.

DELETE /conceptschemes/{scheme_id}/c/{c_id}¶

Remove the concept with id c_id. The response body will contain the last representation known by the service.

Example request:

DELETE /conceptschemes/TREES/c/1 HTTP/1.1
Host: demo.atramhasis.org
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "uri": "urn:x-atramhasis-demo:TREES:1",
    "type": "concept",
    "broader": [],
    "narrower": [],
    "related": [],
    "labels": [
        {
            "type": "prefLabel",
            "language": "en",
            "label": "The Larch"
        }, {
            "type": "prefLabel",
            "language": "nl",
            "label": "De Lariks"
        }
    ],
    "notes": []
}

Parameters:

scheme_id – The identifier for a certain concept scheme.
c_id – The identifier for a certain concept or collection.

Request Headers:

Accept – The response content type depends on this header. Currently only application/json is supported.

Response Headers:

Content-Type – This service currently always returns application/json

Status Codes:

200 OK – The concept or collection was deleted succesfully.
400 Bad Request – The concept or collection could not be edited because the submitted json was invalid due to eg. validation errors.
404 Not Found – The conceptscheme scheme_id or the concept or collection c_id does not exist.
405 Method Not Allowed – The concept or collection could not be deleted because the conceptscheme scheme_id is a readonly conceptscheme.
409 Conflict – The concept or collection could not be deleted because Atramhasis has determined that it’s still being used somewhere else. The response body will contain a message and a list of URI’s that are using this concept.

Languages¶

Apart from the main services, Atramhasis exposes some secondary services that deal with languages.

GET /languages¶

List all languages known to this Atramhasis instance.

Please bear in mind that these are not all known IANA language tags, but a subset used in this Atramhasis instance. This is used to populate drop down lists and such.

Example request:

GET /languages HTTP/1.1
Host: demo.atramhasis.org
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {"id": "la", "name": "Latin"},
    {"id": "nl", "name": "Dutch"},
    {"id": "en", "name": "English"},
    {"id": "fr", "name": "French"},
    {"id": "de", "name": "German"}
]

Parameters:

sort – Which field to sort on. Use - and + to indicate sort order. Eg. id or +id sort ascending on id, -name sort descending on name.

Request Headers:

Accept – The response content type depends on this header. Currently only application/json is supported.

Response Headers:

Content-Type – This service currently always returns application/json

Status Codes:

200 OK – The list of languages was returned.

GET /languages/{language_id}¶

Get information on a certain language.

Please bear in mind this will only work for languages known to this Atramhasis instance. Valid IANA languages not known to this instance will not work.

Example request:

GET /languages HTTP/1.1
Host: demo.atramhasis.org
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "la",
    "name": "Latin"
}

Request Headers:

Accept – The response content type depends on this header. Currently only application/json is supported.

Response Headers:

Content-Type – This service currently always returns application/json

Status Codes:

200 OK – The language was found.
404 Not Found – The language was not found in this instance.

PUT /languages/{language_id}¶

Update the information on a certain language or create an entry for a new one.

The user is required to submit the language_id and this must be a valid IANA language tag.

Example request:

PUT /languages/nl-BE HTTP/1.1
Host: demo.atramhasis.org
Accept: application/json
Content-Type: application/json

{
    "id": "nl-BE",
    "name": "Dutch (Flanders)"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "nl-BE",
    "name": "Dutch (Flanders)"
}

Request Headers:

Accept – The response content type depends on this header. Currently only application/json is supported.

Response Headers:

Content-Type – This service currently always returns application/json

Status Codes:

200 OK – The language was updated or added.
400 Bad Request – The request could not be executed because of problems with the submitted data. Most likely you are submitting an invalid IANA langage code.

DELETE /languages/{language_id}¶

Delete a language from this Atramhasis instance.

Example request:

DELETE /languages/nl-BE HTTP/1.1
Host: demo.atramhasis.org
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "nl-BE",
    "name": "Dutch (Flanders)"
}

Request Headers:

Accept – The response content type depends on this header. Currently only application/json is supported.

Response Headers:

Content-Type – This service currently always returns application/json

Status Codes:

200 OK – The language was deleted.
404 Not Found – The language was not found in this instance.

Services¶

Pyramid_skosprovider¶

Atramhasis¶

Concepts and collections¶

Languages¶

Table of Contents

Previous topic

Next topic

This Page