Services

Atramhasis can be used fully with a SOA. While we provide a public and and a administrators 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.

Read Services

The basic read services are being provided by Pyramid Skosprovider. These allow you to read conceptschemes, search for concepts and collections and integrate the Atramhasis backend into other applications. Maintain you thesaurus in one database and use it in several other applications.

Write Services

The 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

{
    "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

{
    "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

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