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: - 201 Created – The container was added succesfully.
- 404 Not Found – The collection collection_key does not exist.
-
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-Type – application/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-Type – application/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-Type – application/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.