Services

The augeias provides services on Collections, Containers and Objects. You can think of them as a three-leveled hierarchy. At the top there are the collections. Each collection contains containers. And within each container are 1 or more objects.

GET /collections

Show a list of all collections. Every collection is a set of containers. They might have some sort of meaning as defined by the implementer. In practice quite often there will be a collection for every application.

Example request

GET /collections HTTP/1.1
Host: augeias.onroerenderfgoed.be
Accept: application/json

Example response

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

[
    {
        'collection_key': 'default',
        'uri': 'https://storage.onroerenderfgoed.be/collections/default'
    } , {
        'collection_key': 'my_collection',
        'uri': 'https://storage.onroerenderfgoed.be/collections/my_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
POST /collections/{collection_key}/containers

Create a new container. The server will generate a random container key.

Example request:

POST /collections/mine/containers HTTP/1.1
Host: augeias.onroerenderfgoed.be
Accept: application/json

Example response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://storage.onroerenderfgoed.be/collections/mine/containers/6ed5a007-41cf-49ed-8cb8-184fa5f48e42

{
    'container_key': '6ed5a007-41cf-49ed-8cb8-184fa5f48e42',
    'uri': 'https://storage.onroerenderfgoed.be/collections/mine/containers/6ed5a007-41cf-49ed-8cb8-184fa5f48e42'
}
Parameters:
  • collection_key – Key for the collection within which the container will be placed.
Request Headers:
 
  • Accept – The response content type depends on this header. Currently only application/json is supported.
Response Headers:
 
  • Location – The url where the newly added container can be found.
  • Content-Type – This service currently always returns application/json
Status Codes:
PUT /collections/{collection_key}/containers/{container_key}

Create a new container. Allowsyou to choose your own container key. If the container already exists, nothing will happen.

Example request:

PUT /collections/mine/containers/abcd HTTP/1.1
Host: augeias.onroerenderfgoed.be
Accept: application/json

Example response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://storage.onroerenderfgoed.be/collections/mine/containers/abcd

{
    'container_key': 'abcd'
    'uri': 'https://storage.onroerenderfgoed.be/collections/mine/containers/abcd'
}
Parameters:
  • collection_key – Key for the collection within which the container will be placed.
  • container_key – Key for the container that will be created.
Request Headers:
 
  • Accept – The response content type depends on this header. Currently only application/json is supported.
Response Headers:
 
  • Location – The url where the newly added container can be found.
  • Content-Type – This service currently always returns application/json
Status Codes:
  • 200 OK – The container already existed.
  • 201 Created – The container was added succesfully.
  • 404 Not Found – The collection collection_key does not exist.
DELETE /collections/{collection_key}/containers/{container_key}

Remove a container and all the objects in it.

Example request:

DELETE /collections/mine/containers/abcd HTTP/1.1
Host: augeias.onroerenderfgoed.be
Accept: application/json

Example response:

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

{
    'container_key': 'abcd'
    'uri': 'https://storage.onroerenderfgoed.be/collections/mine/containers/abcd'
}
Parameters:
  • collection_key – Key for the collection where the container lives.
  • container_key – Key for the container that will be deleted.
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 container was deleted.
  • 404 Not Found – The collection collection_key does not exist or the container container_key does not exist within this collection.
GET /collections/{collection_key}/containers/{container_key}

Show all objects present in this container.

Example request:

GET /collections/mine/containers/a311efb7-f125-4d0a-aa26-69d3657a2d06 HTTP/1.1
Host: augeias.onroerenderfgoed.be
Accept: application/json

Example response:

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

[
    "square",
    "small",
    "medium",
    "original",
    "large",
    "full"
]
Parameters:
  • collection_key – Key for the collection where the container lives.
  • container_key – Key for the container that will be queried.
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 container exists.
  • 404 Not Found – The collection collection_key or the container container_key does not exist.
HEAD /collections/{collection_key}/containers/{container_key}/{object_key}

Fetch metadata on a object without actually fetching the object.

Example request:

HEAD /collections/mine/containers/a311efb7-f125-4d0a-aa26-69d3657a2d06/full HTTP/1.1
Host: augeias.onroerenderfgoed.be
Accept: application/json

Example response:

HTTP/1.1 200 OK
Date: Fri, 30 Oct 2015 07:11:44 GMT
Server: Apache/2.4.7 (Ubuntu)
Content-type: image/jpeg
Content-Length: 23562
Parameters:
  • collection_key – Key for the collection where the container lives.
  • container_key – Key for the container where the object lives.
  • object_key – Key for the object that will be fetched
Status Codes:
  • 200 OK – The object was found.
  • 404 Not Found – The collection collection_key or the container container_key or the object_key does not exist.
GET /collections/{collection_key}/containers/{container_key}/{object_key}

Fetch an object from a container.

Example request:

GET /collections/mine/containers/a311efb7-f125-4d0a-aa26-69d3657a2d06/full HTTP/1.1
Host: augeias.onroerenderfgoed.be
Accept: application/json

Example response:

HTTP/1.1 200 OK
Date: Fri, 30 Oct 2015 07:11:44 GMT
Server: Apache/2.4.7 (Ubuntu)
Content-type: image/jpeg
Content-Length: 23562

<snipped>
Parameters:
  • collection_key – Key for the collection where the container lives.
  • container_key – Key for the container where the object lives.
  • object_key – Key for the object that will be fetched
Status Codes:
  • 200 OK – The object was found.
  • 404 Not Found – The collection collection_key or the container container_key or the object_key does not exist.
GET /collections/{collection_key}/containers/{container_key}/{object_key}/meta

Fetch object info (mimetype, size, time last modification).

Example request:

GET /collections/mine/containers/a311efb7-f125-4d0a-aa26-69d3657a2d06/full/meta HTTP/1.1
Host: augeias.onroerenderfgoed.be
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-type: image/jpeg

{
        "time_last_modification": "2017-08-18T13:52:25.970242",
        "mime": "image/jpeg",
        "size": 11370
}
Parameters:
  • collection_key – Key for the collection where the container lives.
  • container_key – Key for the container where the object lives.
  • object_key – Key for the object that will be fetched
Status Codes:
  • 200 OK – The object was found.
  • 404 Not Found – The collection collection_key or the container container_key or the object_key does not exist.
POST /collections/{collection_key}/containers/{container_key}

Create a new object. The server will generate a random object key.

Example request:

POST /collections/mine/containers/mine_container HTTP/1.1
Host: augeias.onroerenderfgoed.be
Content-Type: application/octet-stream
Accept: application/json

Example response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://storage.onroerenderfgoed.be/collections/mine/containers/mine_container/6ed5a007-41cf-49ed-8cb8-184fa5f48e42

{
    'container_key': 'mine_container',
    'object_key': '6ed5a007-41cf-49ed-8cb8-184fa5f48e42',
    'collection_key': 'mine'
    'uri': 'https://storage.onroerenderfgoed.be/collections/mine/containers/mine_container/6ed5a007-41cf-49ed-8cb8-184fa5f48e42'
}
Parameters:
  • collection_key – Key for the collection where the container lives.
  • container_key – Key for the container where the object lives.
  • object_key – Key for the object that will be created or updated.
Request Headers:
 
  • Content-Typeapplication/json or application/octet-stream
  • 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:
  • 201 Created – The object and the key were created.
  • 404 Not Found – The collection collection_key or the container container_key does not exist.
PUT /collections/{collection_key}/containers/{container_key}/{object_key}

Add or update an object in a container.

If an object with this key already exists, it will be overwritten. If not, it will be created.

Example request:

PUT /collections/mine/containers/a311efb7-f125-4d0a-aa26-69d3657a2d06/circle HTTP/1.1
Host: augeias.onroerenderfgoed.be
Content-Type: application/octet-stream
Accept: application/json

Exmaple response:

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

{
    'uri': 'https://id.erfgoed.net/storage/collections/mine/containers/a311efb7-f125-4d0a-aa26-69d3657a2d06/circle',
    'object_key': 'circle',
    'container_key': 'a311efb7-f125-4d0a-aa26-69d3657a2d06',
    'collection_key': 'mine'
}
Parameters:
  • collection_key – Key for the collection where the container lives.
  • container_key – Key for the container where the object lives.
  • object_key – Key for the object that will be created or updated.
Request Headers:
 
  • Content-Typeapplication/json or application/octet-stream
  • 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 object was updated.
  • 201 Created – There was no object present with this key, it was created.
  • 404 Not Found – The collection collection_key or the container container_key does not exist.
PUT /collections/{collection_key}/containers/{container_key}/{object_key}

Copy an object from one store location into another within the same Augeias instance. The input json data must contain host url, collection_key, container_key and object_key of the object that needs to be copied.

If an object with this key already exists, it will be overwritten. If not, it will be created.

Example request:

PUT /collections/mine/containers/a311efb7-f125-4d0a-aa26-69d3657a2d06/circle HTTP/1.1
Host: augeias.onroerenderfgoed.be
Content-Type: application/json
Accept: application/json

{
  "host_url": "http://augeias.onroerenderfgoed.be",
  "collection_key": "temp",
  "container_key": "container_id",
  "object_key": "circletemp"
}

Exmaple response:

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

{
    "uri": "https://id.erfgoed.net/storage/collections/mine/containers/a311efb7-f125-4d0a-aa26-69d3657a2d06/circle",
    "object_key": "circle",
    "container_key": "a311efb7-f125-4d0a-aa26-69d3657a2d06",
    "collection_key": "mine"
}
Parameters:
  • collection_key – Key for the collection where the container lives.
  • container_key – Key for the container where the object lives.
  • object_key – Key for the object that will be created or updated.
Request Headers:
 
  • Content-Typeapplication/json or application/octet-stream
  • 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 object was copied.
  • 201 Created – There was no object present with this key, it was created.
  • 400 Bad Request – Validation failure. The input data of the object in the json body is not correct.
  • 404 Not Found – The collection collection_key or the container container_key does not exist.
DELETE /collections/{collection_key}/containers/{container_key}/{object_key}

Delete an object from a container.

Example request:

DELETE /collections/mine/containers/a311efb7-f125-4d0a-aa26-69d3657a2d06/full HTTP/1.1
Host: augeias.onroerenderfgoed.be
Accept: application/json

Example response:

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

{
    "uri": "https://id.erfgoed.net/storage/collections/mine/containers/a311efb7-f125-4d0a-aa26-69d3657a2d06/circle",
    "object_key":"full",
    "container_key":"a311efb7-f125-4d0a-aa26-69d3657a2d06",
    "collection_key": "mine"
}
Status Codes:
  • 200 OK – The object was deleted.
  • 404 Not Found – The collection collection_key or the container container_key or the object_key does not exist.