API (0.0.1)

• API
  • GET
    • Complete Collections
      • Collection Aliases (case insensitive)
    • Single Object
  • POST
    • Queries
    • Create
    • Batch Create
  • PUT
    • Update
    • Add Properties
    • Remove Properties
    • Batch Update
  • DELETE
  • Smart objects
  • __rerum

All the following interactions will take place between the server running RERUM and the application server. If you prefer to use the public RERUM server (which I hope you do), the base URL is http://rerum.io/api. All API calls may throw a 403 for unrecognized applications or 500 for server errors. For the moment, JSON is the format for most of the successful responses, but this may be updated, so the .json extension on the calls is helpful.

GET

Complete Collections

• :collection—name of the type requested. See the below for aliases. Example: /res/canvas.json returns all sc:Canvas objects. Default limit is 20; send ?limit=INTEGER to change.

Collection Aliases (case insensitive)

The following may all be used interchangeably within API calls and inside the objects’ type or @type properties.

manifest

http://iiif.io/api/presentation/2#manifest

sc:manifest

sequence

http://iiif.io/api/presentation/2#sequence

sc:sequence

canvas

http://iiif.io/api/presentation/2#canvas

sc:canvas

folio

page

range

http://iiif.io/api/presentation/2#Range

structure

annotationlist

http://iiif.io/api/presentation/2#AnnotationList

annotationlist

annotation

http://www.w3.org/ns/oa#annotation

oa:annotation

transcription

comment

line

Returns an entire collection in RERUM groups objects by type or @type properties. These groups can be very large and these calls should be limited. Consider the query call for a more targeted approach.

Single Object

Returns the single record which matches the RERUM-assigned @id string. This is a quicker way to access single objects without using query.

POST

Queries

The bulk of any application’s interactions with RERUM will be in the queries. This simple format will be made more complex in the future, but should serve the basic needs as it is.

All responses are in a JSON Array, even if only a single record is returned. Submissions may be either JSON objects or Arrays of JSON objects. RERUM will test for property matches, so { "@type" : "sc:Canvas", "label" : "page 46" } will match

{
  "@id": "https://rerum.io/api/res/sc:Canvas/5644406560391168.json",
  "otherContent": [],
  "label": "page 46",
  "width": 730,
  "images": [],
  "height": 1000,
  "@type": "sc:Canvas"
}

**NB: all object queries must include a type or @type property.

Advanced queries will be passed directly into the GCS runQuery() and are expected to be objects with query or GqlQuery at their root. All type and @type queries are normalized based on the aliases.

Create

Add a completely new object to RERUM and receive the location in response.

Accepts only single JSON objects for RERUM storage. Mints a new URI and returns the object’s location as a header. If the object already contains an @id that matches an object in RERUM, it will be updated instead, though update is preferred for that use.

The :collection parameter is normalized based on the aliases and used as a sanity check. If the type or @type does not match the indicated collection, a _collection property must be included to force the object into an incongruent collection. This parameter is also capable of creating new collections dynamically, so this helps prevent simple typos from sending data into strange corners.

Batch Create

The array of JSON objects passed in will be created in the order submitted and the response will have the URI of the new resource or an error message in the body as an array in the same order. Smart objects will be handled a little differently.

The response body will include status and errors as above for 201, 202, 400, etc., but the detail will be much less than a single request. When errors are encountered, the batch process will attempt to continue for all submitted items.

PUT

Update

Update an existing record through reference to its internal RERUM id.

A single object is updated with all properties in the JSON payload. Unnamed properties are not affected. Unknown properties throw 400 (use set). @type will not be normalized in storage and @context for known types are filled upon delivery and may be omitted.

When an object is updated, the @id will be changed, as the previous version will maintain its place in the history of that object. To overwrite the same object, instead of creating a new version, include ?overwrite=true in the request. See Friendly Practices for the rare times when creating a new entry in the history is not wanted and Versioning for an explanation of how each object’s history is maintained in RERUM.

Add Properties

A single object is updated by adding all properties in the JSON payload. If a property already exists, it is overwritten without feedback.

Remove Properties

A single object is updated by dropping all properties in the JSON payload. If a value is included, it must match to be dropped.

Batch Update

The array of JSON objects passed in will be updated in the order submitted and the response will have the URI of the resource or an error message in the body as an array in the same order. Smart objects will be handled a little differently. Batch updating has no equivalent overwrite parameter.

The request path will indicate the action and possible errors. The response body will include status and errors as above for 201, 202, 400, etc., but the detail will be much less than a single request. When errors are encountered, the batch process will attempt to continue for all submitted items.

DELETE

Mark an object as deleted. Deleted objects are not included in query results.

There is no batch DELETE planned.

Smart objects

Known things in RERUM gain superpowers to save the embedded items and update batches cleverly. To trigger this behavior, add ?recursive=true to create or update requests. GET the new object from the location returned to learn the new URIs assigned to the embedded entities.

In fact, the recursive flag will tell RERUM to traverse any object and look for these known types to also update, but the standard structure of IIIF objects means that the action will be much more reliable.

__rerum

Each object has an immutable property called __rerum containing a metadata object about the record retreived, such as it exists at the time.

In the future, this may be encoded as an annotation on the object, using existing vocabularies, but for now the applications accessing RERUM will need to interpret these data if it is relevant.