EditionAPIStructures

Draft 2015-03-26

Edition API Structures

Basic Types

ID

An integer serving as the primary key of a table.

Target URI

Within Tradamus, each entity can be uniquely identified by means of a URI-like string (e.g. "edition/2" or "annotation/1234").

In some cases, these URIs may include a fragment to further specify the target. Thus, "parallel/11#3" specifies to the portion of "parallel/11" which draws from "witness/3". For a Canvas-targetted annotation, the fragment can specify the portion of the Canvas which is targetted (e.g. "canvas/12#xywh=10,10,320,240" to target a rectangular area within "canvas/12").

Edition

{
   "id": ID,
   "title": string,
   "creator": User ID,
   "permissions": array of long-form Permissions,
   "witnesses": array of short-form Witnesses,
   "outlines": array of Outline IDs
}

Outline

Returned by /outline/outlID.

{
   "id": ID,
   "title": string,
   "index":int,
   "bounds": array of Annotations (null for full-Edition outline)
   "edition": Edition ID,
   "decisions": array of Decisions
}

Decision

{
   "id": ID,
   "content": string,
   "type": "tr-decision",
   "motes": array of Annotations having "type":"tr-mote"
}

Annotation

{
   "id": ID,
   "content": string,
   "type": string,
   "target": URI of Tradamus object (may include fragment),
   "startPage": Page ID,
   "startOffset": int,
   "endPage": Page ID,
   "endOffset": int,
   "canvas": URI of Canvas (may include fragment)
   "attributes": map containing key/value pairs,
   "tags": string,
   "modifiedBy": User ID,
   "approvedBy": User ID
}

Permission

Long-form

Includes name and email address of User associated so that an extra call is not necessary. Returned in Edition.permissions, Manifest.permissions, Transcription.permissions, and Publication.permissions.

{
   "id": ID,
   "role": "NONE"|"VIEWER"|"CONTRIBUTOR"|"EDITOR"|"OWNER",
   "user": User ID
   "name": User's full name,
   "mail": User's email address,
   "target": Edition, Manifest, or Transcription URI
}

Short-form

Used when PUTting to /edition/edID/permissions, /transcription/transcrID/permissions, /manifest/manID/permissions, or /publication/pubID/permissions.

{
   "role": "NONE"|"VIEWER"|"CONTRIBUTOR"|"EDITOR"|"OWNER",
   "user": User ID (0 to indicate the "public sharing" user).
   "target": Edition, Manifest, or Transcription URI
}

Witness

Short-form

Returned in Edition.witnesses.

{
   "id": ID,
   "title": string,
   "siglum" string
}