Recent changes to EndpointPermissions

EndpointPermissions modified by Domhnall101

Domhnall101 — Tue, 06 Oct 2015 19:47:20 -0000

--- v6
+++ v7
@@ -1,4 +1,5 @@
-This document describes the access permissions which are required to use the various Tradamus endpoints.  The endpoints themselves are more full described in [Tradamus Server API].
+##Endpoint Permissions
+This document describes the access permissions which are required to use the various Tradamus endpoints.  The endpoints themselves are more full described in [Tradamus Server API](TradamusServerAPI).

 There are five ranked levels of access:  `NONE`, `VIEWER`, `CONTRIBUTOR`, `EDITOR`, and `OWNER`.  If a user has a particular level of access to a resource, they also implicitly have all the lower levels of access.

Endpoint Permissions modified by Eric Smith

Eric Smith — Thu, 18 Sep 2014 01:08:38 -0000

--- v5
+++ v6
@@ -12,7 +12,7 @@

 These levels are relative to a given resource.  A particular user could have `OWNER` access to one edition while  having no access at all to other editions.

-Permissions can currently be set at three different points:  the edition, the transcription, and the manifest.  When verifying permissions, they are checked at the edition level first; if the user has sufficient permissions to access the edition, permissions are then checked at the transcription or manifest level.  Accordingly, transcription and manuscript permissions can only be used to make access more restrictive.
+Permissions can currently be set at three different points:  the edition, the transcription, and the manifest.  When verifying permissions, they are checked at the edition level first; if the user has sufficient permissions to access the edition, permissions are then checked at the transcription or manifest level.  Accordingly, transcription and manifestt permissions can only be used to make access more restrictive.

 Also new is the notion of annotations being vetted or unvetted.  When a user with `CONTRIBUTOR` access adds an annotation, it is only visible to themselves and to users with `EDITOR` access.  Once an `EDITOR` has approved an annotation, it becomes visible to all users with `VIEWER` access.

Endpoint Permissions modified by Eric Smith

Eric Smith — Mon, 14 Apr 2014 17:45:13 -0000

--- v4
+++ v5
@@ -92,7 +92,7 @@
 ### Set edition metadata ###
 Endpoint: /edition/*edID*/metadata
 Method: PUT
-Access: `CONTRIBUTOR` on the edition.  If access level is just `CONTRIBUTOR`, the call will only modify metadata added by the current user.
+Access: `CONTRIBUTOR` on the edition.  If access level is just `CONTRIBUTOR`, the call will fail with a 403 if it attempts to modify any metadata which belong to another user.

 ### Get edition decisions ###
 Endpoint: /edition/*edID*/decisions
@@ -102,7 +102,7 @@
 ### Set edition decisions ###
 Endpoint: /edition/*edID*/decisions
 Method: PUT
-Access: `CONTRIBUTOR` on the edition.  If access level is just `CONTRIBUTOR`, the call will only modify decisions added by the current user.
+Access: `CONTRIBUTOR` on the edition.  If access level is just `CONTRIBUTOR`, the call will fail with a 403 if it attempts to modify any decisions which belong to another user.

 ### Set edition permissions ###
 Endpoint: /edition/*edID*/permissions
@@ -140,7 +140,7 @@
 ### Set witness metadata ###
 Endpoint: /witness/*witID*/metadata
 Method: PUT
-Access: `CONTRIBUTOR` on the edition.  If access level is just `CONTRIBUTOR`, the call will only modify metadata added by the current user.
+Access: `CONTRIBUTOR` on the edition.  If access level is just `CONTRIBUTOR`, the call will fail with a 403 if it attempts to modify any metadata which belong to another user.

 ### Delete a witness ###
 Endpoint:  /witness/*witID*
@@ -191,7 +191,7 @@
 ### Set page annotations ###
 Endpoint:  /page/*pageID*/annotations
 Method: PUT
-Access: `CONTRIBUTOR` on the transcription.  If access level is just `CONTRIBUTOR`, the call will only modify annotations added by the current user.
+Access: `CONTRIBUTOR` on the transcription.  If access level is just `CONTRIBUTOR`, the call will fail with a 403 if it attempts to modify any annotations which belong to another user.

 ### Get page lines ###
 Endpoint:  /page/*pgID*/lines
@@ -201,7 +201,7 @@
 ### Set page lines ###
 Endpoint:  /page/*pageID*/lines
 Method: PUT
-Access: `CONTRIBUTOR` on the transcription.  If access level is just `CONTRIBUTOR`, the call will only modify lines added by the current user.
+Access: `CONTRIBUTOR` on the transcription.  If access level is just `CONTRIBUTOR`, the call will fail with a 403 if it attempts to modify any lines which belong to another user.

 ## 7. Manifests ##
@@ -242,7 +242,7 @@
 ### Set canvas annotations ###
 Endpoint:  /canvas/*canvID*/annotations
 Method: PUT
-Access: `CONTRIBUTOR` on the manifest.  If access level is just `CONTRIBUTOR`, the call will only modify annotations added by the current user.
+Access: `CONTRIBUTOR` on the manifest.  If access level is just `CONTRIBUTOR`, the call will fail with a 403 if it attempts to modify any annotations which belong to another user.

 ### Get canvas lines ###
 Endpoint:  /canvas/*canvID*/lines
@@ -252,7 +252,7 @@
 ### Set canvas lines ###
 Endpoint:  /canvas/*canvID*/lines
 Method: PUT
-Access: `CONTRIBUTOR` on the manifest.  If access level is just `CONTRIBUTOR`, the call will only modify lines added by the current user.
+Access: `CONTRIBUTOR` on the manifest.  If access level is just `CONTRIBUTOR`, the call will fail with a 403 if it attempts to modify any lines which belong to another user.

 ## 9. Annotations ##
@@ -265,13 +265,13 @@
 ### Set annotation details ###
 Endpoint:  /annotation/*annID*
 Method: PUT
-Access: `CONTRIBUTOR` on the transcription or the manifest.  If the access level is just `CONTRIBUTOR`, the call can only modify annotations added by the current user.
+Access: `CONTRIBUTOR` on the transcription or the manifest.  If access level is just `CONTRIBUTOR`, the call will fail with a 403 if it attempts to modify an annotation which belongs to another user.

 ### Delete an annotation ###
 Endpoint:  /annotation/*annID*
 Method: DELETE
-Access: `CONTRIBUTOR` on the transcription or the manifest.  If the access level is just `CONTRIBUTOR`, the call can only delete annotations added by the current user.
+Access: `CONTRIBUTOR` on the transcription or the manifest.  If the access level is just `CONTRIBUTOR`, the call can only delete an annotation belonging to the current user.

 ## 10. Collation ##

Endpoint Permissions modified by Eric Smith

Eric Smith — Thu, 03 Apr 2014 16:15:21 -0000

--- v3
+++ v4
@@ -6,13 +6,15 @@
 ------------- | ------
 `NONE`        | None
 `VIEWER`      | Read-only access.
-`CONTRIBUTOR` | Can add new elements (i.e. annotations) but these will be unvetted.
-`EDITOR`      | Can add vetted elements.  Can vet elements for `CONTRIBUTOR`s.
+`CONTRIBUTOR` | Can add new annotations but these will be unvetted.
+`EDITOR`      | Can add fully-vetted annotations.  Can vet annotations for `CONTRIBUTOR`s.
 `OWNER`       | Can assign permissions.

 These levels are relative to a given resource.  A particular user could have `OWNER` access to one edition while  having no access at all to other editions.

 Permissions can currently be set at three different points:  the edition, the transcription, and the manifest.  When verifying permissions, they are checked at the edition level first; if the user has sufficient permissions to access the edition, permissions are then checked at the transcription or manifest level.  Accordingly, transcription and manuscript permissions can only be used to make access more restrictive.
+
+Also new is the notion of annotations being vetted or unvetted.  When a user with `CONTRIBUTOR` access adds an annotation, it is only visible to themselves and to users with `EDITOR` access.  Once an `EDITOR` has approved an annotation, it becomes visible to all users with `VIEWER` access.

 ## 1. Users ##

@@ -169,30 +171,37 @@
 ### Get page details ###
 Endpoint:  /page/*pageID*
 Method: GET
+Access: `VIEWER` on the transcription.

 ### Set page details ###
 Endpoint:  /page/*pageID*
 Method: PUT
+Access: `EDITOR` on the transcription.

 ### Add a page annotation ###
 Endpoint: /page/*pgID*/annotations
 Method: POST
+Access: `CONTRIBUTOR` on the transcription.

 ### Get page annotations ###
 Endpoint:  /page/*pgID*/annotations
 Method: GET
+Access: `VIEWER` on the transcription.

 ### Set page annotations ###
 Endpoint:  /page/*pageID*/annotations
 Method: PUT
+Access: `CONTRIBUTOR` on the transcription.  If access level is just `CONTRIBUTOR`, the call will only modify annotations added by the current user.

 ### Get page lines ###
 Endpoint:  /page/*pgID*/lines
 Method: GET
+Access: `VIEWER` on the transcription.

 ### Set page lines ###
 Endpoint:  /page/*pageID*/lines
 Method: PUT
+Access: `CONTRIBUTOR` on the transcription.  If access level is just `CONTRIBUTOR`, the call will only modify lines added by the current user.

 ## 7. Manifests ##
@@ -200,10 +209,12 @@
 ### Get manifest details ###
 Endpoint:  /manifest/*manID*
 Method:  GET
+Access: `VIEWER` on the manifest.

 ### Set manifest permissions ###
 Endpoint:  /manifest/*manID*/permissions
 Method:  PUT
+Access: `OWNER` on the manifest.

 ## 8. Canvasses ##
@@ -211,30 +222,37 @@
 ### Get canvas details ###
 Endpoint:  /canvas/*canvID*
 Method:  GET
+Access: `VIEWER` on the manifest.

 ### Set canvas details ###
 Endpoint:  /canvas/*canvID*
 Method: PUT
+Access: `EDITOR` on the manifest.

 ### Add a canvas annotation ###
 Endpoint: /canvas/*canvID*/annotations
 Method: POST
+Access: `CONTRIBUTOR` on the manifest.

 ### Get canvas annotations ###
 Endpoint:  /canvas/*canvID*/annotations
 Method:  GET
+Access: `VIEWER` on the manifest.

 ### Set canvas annotations ###
 Endpoint:  /canvas/*canvID*/annotations
 Method: PUT
+Access: `CONTRIBUTOR` on the manifest.  If access level is just `CONTRIBUTOR`, the call will only modify annotations added by the current user.

 ### Get canvas lines ###
 Endpoint:  /canvas/*canvID*/lines
 Method: GET
+Access: `VIEWER` on the manifest.

 ### Set canvas lines ###
 Endpoint:  /canvas/*canvID*/lines
 Method: PUT
+Access: `CONTRIBUTOR` on the manifest.  If access level is just `CONTRIBUTOR`, the call will only modify lines added by the current user.

 ## 9. Annotations ##
@@ -242,14 +260,18 @@
 ### Get annotation details ###
 Endpoint:  /annotation/*annID*
 Method:  GET
+Access: `VIEWER` on the transcription or the manifest.  In particular, if an annotation is anchored to both the page and the canvas, it is sufficient to have `VIEWER` access on one of the transcription or the manifest.

 ### Set annotation details ###
 Endpoint:  /annotation/*annID*
 Method: PUT
+Access: `CONTRIBUTOR` on the transcription or the manifest.  If the access level is just `CONTRIBUTOR`, the call can only modify annotations added by the current user.
+

 ### Delete an annotation ###
 Endpoint:  /annotation/*annID*
 Method: DELETE
+Access: `CONTRIBUTOR` on the transcription or the manifest.  If the access level is just `CONTRIBUTOR`, the call can only delete annotations added by the current user.

 ## 10. Collation ##
@@ -257,17 +279,21 @@
 ### Full-edition collation ###
 Endpoint:  /collation/*edID*
 Method:  GET
+Access: Only transcriptions with `VIEWER` access will be included in the collation.

 ### Sub-collation ###
 Endpoint:  /collation
 Method:  GET
+Access: Only transcriptions with `VIEWER` access will be included in the collation.

 ## 11. Config ##
 Endpoint:  /config
 Method:  GET
+Access: No restrictions.

 ## 12. Activity Log ##
 Endpoint:  /activity
 Method:  GET
+Access: To be determined.

Endpoint Permissions modified by Eric Smith

Eric Smith — Wed, 02 Apr 2014 23:24:50 -0000

--- v2
+++ v3
@@ -1,45 +1,63 @@
-The following table describes the permission level which is required to access the given endpoint.  The endpoints themselves are more full described in [Tradamus Server API].
-
-There are five ranked levels of permissions:  `NONE`, `VIEWER`, `CONTRIBUTOR`, `EDITOR`, and `OWNER`.  If a user has a particular level of access to a resource, they also implicitly have all the lower levels of access.
-
-Permissions can currently be set at three different points:  the Edition, the Transcription, and the Manifest.  When verifying
+This document describes the access permissions which are required to use the various Tradamus endpoints.  The endpoints themselves are more full described in [Tradamus Server API].
+
+There are five ranked levels of access:  `NONE`, `VIEWER`, `CONTRIBUTOR`, `EDITOR`, and `OWNER`.  If a user has a particular level of access to a resource, they also implicitly have all the lower levels of access.
+
+level         | access
+------------- | ------
+`NONE`        | None
+`VIEWER`      | Read-only access.
+`CONTRIBUTOR` | Can add new elements (i.e. annotations) but these will be unvetted.
+`EDITOR`      | Can add vetted elements.  Can vet elements for `CONTRIBUTOR`s.
+`OWNER`       | Can assign permissions.
+
+These levels are relative to a given resource.  A particular user could have `OWNER` access to one edition while  having no access at all to other editions.
+
+Permissions can currently be set at three different points:  the edition, the transcription, and the manifest.  When verifying permissions, they are checked at the edition level first; if the user has sufficient permissions to access the edition, permissions are then checked at the transcription or manifest level.  Accordingly, transcription and manuscript permissions can only be used to make access more restrictive.

 ## 1. Users ##

 ### Add new user ###
-POST /users
-No restrictions.
+Endpoint: /users
+Method: POST
+Access: No restrictions.

 ### Invite new user ###
-POST /users
-`EDITOR` on associated edition.
+Endpoint: /users
+Method: POST
+Access: `EDITOR` on edition to which user is being invited.

 ### Get user details ###
-GET /user/*userID*
-No restrictions.
+Endpoint: /user/*userID*
+Method: GET
+Access: No restrictions.

 ### Get user details by email ###
-GET /user?mail=*emailAddress*
-No restrictions.
+Endpoint: /user?mail=*emailAddress*
+Method: GET
+Access: No restrictions.

 ### Modify user details ###
-PUT /user/*userID*
-Only *userID* can modify their own details.
+Endpoint: /user/*userID*
+Method: PUT
+Access: Only *userID* can modify their own details.

 ### Reset user password ###
-PUT /user?reset=*emailAddress*
-No restrictions.
+Endpoint: /user?reset=*emailAddress*
+Method: POST
+Access: No restrictions.

 ## 2. Login ##

 ### Log in to Tradamus ###
-POST /login
-No restrictions.
+Endpoint: /login
+Method: POST
+Access: No restrictions.

 ### Check login status ###
-GET /login
-The call always returns the status of the currently logged-in user.
+Endpoint: /login
+Method: GET
+Access: The call always returns the status of the current user.

 ## 3. Editions ##
@@ -47,42 +65,52 @@
 ### Add new edition ###
 Endpoint: /editions
 Method: POST
+Access: No restrictions.  The current user will be granted `OWNER` access to the newly-created edition.

 ### List editions ###
 Endpoint: /editions
 Method: GET
+Access: The call will only return editions for which the current user has `VIEWER` permissions.

 ### Get edition details ###
 Endpoint: /edition/*edID*
 Method: GET
+Access: `VIEWER` on the edition.

 ### Set edition details ###
 Endpoint: /edition/*edID*
 Method: PUT
+Access: `EDITOR` on the edition.

 ### Add an edition metadatum ###
 Endpoint: /edition/*edID*/metadata
 Method: POST
+Access: `CONTRIBUTOR` on the edition.

 ### Set edition metadata ###
 Endpoint: /edition/*edID*/metadata
 Method: PUT
+Access: `CONTRIBUTOR` on the edition.  If access level is just `CONTRIBUTOR`, the call will only modify metadata added by the current user.

 ### Get edition decisions ###
 Endpoint: /edition/*edID*/decisions
 Method: GET
+Access: `VIEWER` on the edition.

 ### Set edition decisions ###
 Endpoint: /edition/*edID*/decisions
 Method: PUT
+Access: `CONTRIBUTOR` on the edition.  If access level is just `CONTRIBUTOR`, the call will only modify decisions added by the current user.

 ### Set edition permissions ###
 Endpoint: /edition/*edID*/permissions
 Method: PUT
+Access: `OWNER` on the edition.

 ### Delete an edition ###
 Endpoint: /edition/*edID*
 Method: DELETE
+Access: `OWNER` on the edition.

 ## 4. Witnesses ##
@@ -90,30 +118,37 @@
 ### Create a new witness ###
 Endpoint: /witnesses
 Method: POST
+Access: `EDITOR` on the edition.

 ### Get witness details ###
 Endpoint:  /witness/*witID*
 Method: GET
+Access: `VIEWER` on the edition.

 ### Set witness details ###
 Endpoint:  /witness/*witID*
 Method:  PUT
+Access: `EDITOR` on the edition.

 ### Add a witness metadatum ###
 Endpoint: /witness/*witID*/metadata
 Method: POST
+Access: `CONTRIBUTOR` on the edition.

 ### Set witness metadata ###
 Endpoint: /witness/*witID*/metadata
 Method: PUT
+Access: `CONTRIBUTOR` on the edition.  If access level is just `CONTRIBUTOR`, the call will only modify metadata added by the current user.

 ### Delete a witness ###
 Endpoint:  /witness/*witID*
 Method: DELETE
+Access: `EDITOR` on the edition.

 ### Recursively get all witness annotations ###
 Endpoint:  /witness/*witID*/annotations
 Method: GET
+Access: `VIEWER` on the edition.  The results will be filtered if access is more restricted at the transcription or manifest levels.

 ## 5. Transcriptions ##
@@ -121,10 +156,12 @@
 ### Get transcription details ###
 Endpoint:  /transcription/*transcrID*
 Method: GET
+Access: `VIEWER` on the transcription.

 ### Set transcription permissions ###
 Endpoint:  /transcription/*transcrID*/permissions
 Method:  PUT
+Access: `OWNER` on the transcription.

 ## 6. Pages ##

Endpoint Permissions modified by Eric Smith

Eric Smith — Wed, 02 Apr 2014 22:37:53 -0000

--- v1
+++ v2
@@ -30,6 +30,9 @@
 PUT /user?reset=*emailAddress*
 No restrictions.

+
+## 2. Login ##
+
 ### Log in to Tradamus ###
 POST /login
 No restrictions.
@@ -38,148 +41,90 @@
 GET /login
 The call always returns the status of the currently logged-in user.

-POST /editions
-GET /editions
-GET /edition/*edID*
-PUT /edition/*edID*
-POST /edition/*edID*/metadata
-PUT /edition/*edID*/metadata
-GET /edition/*edID*/decisions
-PUT /edition/*edID*/decisions
-PUT /edition/*edID*/permissions
-DELETE /edition/*edID*
-
-POST /witnesses
-Method: POST
-Parameters: `edition=`*edID* (required)
-Request content-type: application/json
-Request body: {"title":"My Witness","siglum":"M"}
-Status: 201 on success, 404 if *edID* does not exist.
-Comments:
-This allows the creation of a witness from JSON (non-LD) data.  The "title" and "siglum" fields are required.
-
-### Import JSON-LD witness ###
+
+## 3. Editions ##
+
+### Add new edition ###
+Endpoint: /editions
+Method: POST
+
+### List editions ###
+Endpoint: /editions
+Method: GET
+
+### Get edition details ###
+Endpoint: /edition/*edID*
+Method: GET
+
+### Set edition details ###
+Endpoint: /edition/*edID*
+Method: PUT
+
+### Add an edition metadatum ###
+Endpoint: /edition/*edID*/metadata
+Method: POST
+
+### Set edition metadata ###
+Endpoint: /edition/*edID*/metadata
+Method: PUT
+
+### Get edition decisions ###
+Endpoint: /edition/*edID*/decisions
+Method: GET
+
+### Set edition decisions ###
+Endpoint: /edition/*edID*/decisions
+Method: PUT
+
+### Set edition permissions ###
+Endpoint: /edition/*edID*/permissions
+Method: PUT
+
+### Delete an edition ###
+Endpoint: /edition/*edID*
+Method: DELETE
+
+
+## 4. Witnesses ##
+
+### Create a new witness ###
 Endpoint: /witnesses
 Method: POST
-Parameters: `edition=`*edID* (required)
-Request content-type: application/ld+json
-Request body: single-file IIIF metadata representation
-Status: 201 on success, 404 if *edID* does not exist.
-Comments:
-Currently the only source for this type of file is the JSON-LD export from T-PEN.  The IIIF metadata spec is still under development, and does not appear to yet be supported by any other software.
-
-### Import XML witness ###
-Endpoint: /witnesses
-Method: POST
-Parameters: `edition=`*edID* (required)
-Request content-type: text/xml
-Request body: TEI XML file
-Status:  201 on success, 404 if *edID* does not exist.
-Comments:
-This has so far only been tested with TEI files from Jeffrey Witt's Petrus Plaoul corpus.  The implementation will need to be generalised as we encounter other TEI files.

 ### Get witness details ###
 Endpoint:  /witness/*witID*
 Method: GET
-Request body:  none
-Response body:
-{
-  "id":4,
-  "author":"Petrus Plaoul",
-  "edition":1,
-  "title":"Lectio 1, Prologus \[Vatican Transcription]",
-  "manifest":3,
-  "siglum":"V",
-  "transcription":3,
-  "metadata":\{
-    "editor":"Jeffrey C. Witt",
-    "pubPlace":"Boston, MA"
-  }
-}
-Status:  200 on success, 404 if *witID* does not exist.
-Comments:

 ### Set witness details ###
 Endpoint:  /witness/*witID*
 Method:  PUT
-Request content-type:  application/json
-Request body:  {"author":"New Author", "title":"New Title", "siglum":"New Siglum"}
-Response body:  none
-Status:  204 on success, 404 if *witID* does not exist.
-Comments:
-The request body should contain a JSON object describing the fields to be changed.  Any fields which are omitted from the request will remain unchanged.

 ### Add a witness metadatum ###
 Endpoint: /witness/*witID*/metadata
 Method: POST
-Request content-type: application/json
-Request body: {"type":"colour","content":"turquoise"}
-Response body: none
-Response location: /annotation/*annID*
-Status: 201 on success, 404 if *witID* does not exist.
-Comments:
-The request body should contain a single annotation object.  The Location header of the response gives the caller the ID of the newly-created metadatum.

 ### Set witness metadata ###
 Endpoint: /witness/*witID*/metadata
 Method: PUT
-Request content-type: application/json
-Request body: \[{"type":"colour","content":"turquoise"}]
-Request parameters: `merge=true|false` (default `true`)
-Response body: none
-Status: 204 on success, 404 if *witID* does not exist.
-Comments:
-The request body should contain an array of annotation objects. If the `merge` parameter is `false`, the contents of the array will completely replace the witness' existing metadata; if `merge` is `true` or omitted, the PUT will only affect metadata objects included in the request body.  In either case, the call will create any objects found in the request body which don't already exist.
-

 ### Delete a witness ###
 Endpoint:  /witness/*witID*
 Method: DELETE
-Request body:  none
-Response body:  none
-Status:  204 on success.
-Comments:
-Deletes the single witness identified by *witID*.  Associated transcriptions, pages, manifests, canvasses, images, and annotations will also be deleted.

 ### Recursively get all witness annotations ###
 Endpoint:  /witness/*witID*/annotations
 Method: GET
-Request body:  none
-Response body:  
-Status:  200 on success, 404 if *witID* does not exist.
-Comments:
-Convenience function which aggregates the annotations from all canvasses and pages associated with the witness.

 ## 5. Transcriptions ##
-
-Each witness has exactly one corresponding transcription object, which is created automatically when the witness is created.  A transcription contains some metadata (e.g. the editor name), but its main purpose is to serve as a container to group together all the pages.

 ### Get transcription details ###
 Endpoint:  /transcription/*transcrID*
 Method: GET
-Request body:  none
-Response body:  {
-  "id":1,"editor":"J. Witt",
-  "pages":\[
-    {"id":1000,"title":"1r"},
-    {"id":6001,"title":"1v"}
-  ]
-}
-Status:  200 on success, 404 if *transcrID* does not exist.
-Comments:
-The "pages" field of the transcription object provides an array with the IDs and titles of all pages associated with said transcription.

 ### Set transcription permissions ###
 Endpoint:  /transcription/*transcrID*/permissions
 Method:  PUT
-Request content-type:  application/json
-Request body:  \[{"user":*uID*, "role":"OWNER"}]
-Request parameters: `merge=true|false` (default `true`)
-Response body:  none
-Status: 204 on success, 404 if *transcrID* does not exist, 409 if the request body refers to a nonexistent user ID.
-Comments:
-The request body should contains an array of user permissions objects.  The "user" field of each object should contain a user ID, and the "role" field one of "NONE", "VIEWER", "CONTRIBUTOR", "EDITOR", or "OWNER", identifying the permissions that will be granted to that user for the given transcription.  If the `merge` parameter is `false`, the contents of the array will completely replace the transcription's existing permissions; if it is `true` or omitted, only permissions mentioned in the request body will be affected.

 ## 6. Pages ##
@@ -187,97 +132,41 @@
 ### Get page details ###
 Endpoint:  /page/*pageID*
 Method: GET
-Request body:  none
-Response body:  {"id":5, "text":"Quantum ad istud…", "title":"S4r.jpg", "index":4, "transcription":1}
-Status:  200 on success, 404 if *pageID* does not exist.
-Comments:
-The "index" field contains the page's index within the transcription as a whole.  If the "annotations" parameter is specified, the response will include an array of all annotation objects attached to the page.  Similarly, specifying the "lines" parameter will include an array of all line objects.

 ### Set page details ###
 Endpoint:  /page/*pageID*
 Method: PUT
-Request body:  {"id":5, "text":"Quantum ad istud…"}
-Response body:  none
-Status:  204 on success, 404 if *pageID* does not exist.
-Comments:
-The JSON object in the request body should contain all fields which are to be modified; fields which aren't being changed can be omitted.  Changing the page's "text" property may result in annotations being recalculated.  Changing the page's "index" property can be used to reorder pages within the transcription.

 ### Add a page annotation ###
 Endpoint: /page/*pgID*/annotations
 Method: POST
-Request content-type: application/json
-Request body: {"type":"colour","content":"turquoise"}
-Response body: none
-Response location: /annotation/*annID*
-Status: 201 on success, 404 if *pgID* does not exist.
-Comments:
-The request body should contain a single annotation object.  The Location header of the response gives the caller the ID of the newly-created annotation.

 ### Get page annotations ###
 Endpoint:  /page/*pgID*/annotations
 Method: GET
-Request body:  none
-Response body:   \[{"id":38042,"startOffset":0,"endOffset":46,"type":"line","purpose":"LB","content":"fratres nostri quae acta sunt et quae difinita","motivation":"sc:painting","canvas":2085,"bounds":{"height":50,"width":627,"y":76,"x":40},"startPage":2085,"endPage":2085},…]
-Status:  200 on success, 404 if *pgID* does not exist.
-Comments:
-Response contains an array with all annotations found on the given page.  This includes multi-page annotations whose page range includes the page in question.  Since lines are annotations, they will be included in the response.

 ### Set page annotations ###
 Endpoint:  /page/*pageID*/annotations
 Method: PUT
-Request body:  \[{"id":38042,"startOffset":0,"endOffset":46,"type":"line","purpose":"LB","content":"fratres nostri quae acta sunt et quae difinita","motivation":"sc:painting","canvas":2085,"bounds":{"height":50,"width":627,"y":76,"x":40},"startPage":2085,"endPage":2085},…]
-Request parameters:  `merge=true|false` (default `true`)
-Response body:  none
-Status:  204 on success, 404 if *pageID* does not exist.
-Comments:
-The JSON array in the request body should contain new values for the page's annotations.  If the `merge` parameter is `false`, the existing annotations will be completely replaced; if it is `true` or omitted, only annotations mentioned in the request body will be affected.  For the purposes of this endpoint, a page's annotations are considered to be all annotations whose "startPage" to "endPage" range includes *pageID*.

 ### Get page lines ###
 Endpoint:  /page/*pgID*/lines
 Method: GET
-Request body:  none
-Response body: \[
-  {"id":34796,"startOffset":0,"endOffset":55,"selector":null,"type":"line","purpose":"LB","content":"episcopum fuisse aut esse neque ipsos qui ab eo ordina-","attributes":null,"startPage":6118,"endPage":6118,"bounds":{"height":94,"width":662,"y":9,"x":53},"canvas":6118},
-  …
-]
-Status:  200 on success, 404 if *pgID* does not exist.
-Comments:
-Response contains an array with all line annotations found on the given page.

 ### Set page lines ###
 Endpoint:  /page/*pageID*/lines
 Method: PUT
-Request body:  \[{"id":38042,"startOffset":0,"endOffset":46,"type":"line","purpose":"LB","content":"fratres nostri quae acta sunt et quae difinita","motivation":"sc:painting","canvas":2085,"bounds":{"height":50,"width":627,"y":76,"x":40},"startPage":2085,"endPage":2085},…]
-Request parameters:  `merge=true|false` (default `true`)
-Response body:  none
-Status:  204 on success, 404 if *pageID* does not exist.
-Comments:
-The JSON array in the request body should contain new values for the page's lines.  If the `merge` parameter is `false`, the existing lines will be completely replaced; if it is `true` or omitted, only lines mentioned in the request body will be affected.  For the purposes of this endpoint, a page's lines are considered to be all annotations whose "purpose" is "LB" and whose "startPage" is *pageID*.

 ## 7. Manifests ##
-
-Each witness has exactly one corresponding manifest object, which is created automatically when the witness is created.  A manifest will eventually contain some metadata, but its main purpose is to serve as a container to group together all the canvasses.

 ### Get manifest details ###
 Endpoint:  /manifest/*manID*
 Method:  GET
-Request body:  none
-Response body:  {"id":3,"canvasses":\[9,10,11,12]}
-Status:  200 on success, 404 if *manID* does not exist.
-Comments:
-The "canvasses" field of the manifest object provides an array with the IDs of all canvasses associated with said manifest.

 ### Set manifest permissions ###
 Endpoint:  /manifest/*manID*/permissions
 Method:  PUT
-Request content-type:  application/json
-Request body:  \[{"user":*uID*, "role":"OWNER"}]
-Request parameters: `merge=true|false` (default `true`)
-Response body:  none
-Status: 204 on success, 404 if *manID* does not exist, 409 if the request body refers to a nonexistent user ID.
-Comments:
-The request body should contains an array of user permissions objects.  The "user" field of each object should contain a user ID, and the "role" field one of "NONE", "VIEWER", "CONTRIBUTOR", "EDITOR", or "OWNER", identifying the permissions that will be granted to that user for the given manifest.  If the `merge` parameter is `false`, the contents of the array will completely replace the manifest's existing permissions; if it is `true` or omitted, only permissions mentioned in the request body will be affected.

 ## 8. Canvasses ##
@@ -285,69 +174,30 @@
 ### Get canvas details ###
 Endpoint:  /canvas/*canvID*
 Method:  GET
-Request body:  none
-Response body:  {"id":12,"title":"R2v.jpg","page":12,"manifest":3}
-Status:  200 on success, 404 if *canvID* does not exist.
-Comments:
-The "index" field contains the canvas' index within the manifest as a whole.

 ### Set canvas details ###
 Endpoint:  /canvas/*canvID*
 Method: PUT
-Request body:  {"id":5,"title":"Frontispiece"}
-Response body:  none
-Status:  204 on success, 404 if *canvID* does not exist.
-Comments:
-The JSON object in the request body should contain all fields which are to be modified; fields which aren't being changed can be omitted.  Changing the canvas' "index" property can be used to reorder canvasses within the manifest.

 ### Add a canvas annotation ###
 Endpoint: /canvas/*canvID*/annotations
 Method: POST
-Request content-type: application/json
-Request body: {"type":"colour","content":"turquoise"}
-Response body: none
-Response location: /annotation/*annID*
-Status: 201 on success, 404 if *canvID* does not exist.
-Comments:
-The request body should contain a single annotation object.  The Location header of the response gives the caller the ID of the newly-created annotation.

 ### Get canvas annotations ###
 Endpoint:  /canvas/*canvID*/annotations
 Method:  GET
-Request body:  none
-Response body:  \[{"id":36748,"startOffset":0,"endOffset":58,"type":"line","purpose":"LB","content":"de adulterio accussant et non habent latentia peccata uin-","motivation":"sc:painting","canvas":2033,"bounds":{"height":66,"width":601,"y":64,"x":31},"startPage":2033,"endPage":2033},…]
-Status:  200 on success, 404 if *canvID* does not exist.
-Comments:
-Response contains an array with all annotations found on the given canvas.  Since lines are annotations, they will be included in the response.

 ### Set canvas annotations ###
 Endpoint:  /canvas/*canvID*/annotations
 Method: PUT
-Request body:  \[{"id":38042,"startOffset":0,"endOffset":46,"type":"line","purpose":"LB","content":"fratres nostri quae acta sunt et quae difinita","motivation":"sc:painting","canvas":2085,"bounds":{"height":50,"width":627,"y":76,"x":40},"startPage":2085,"endPage":2085},…]
-Request parameters:  `merge=true|false` (default `true`)
-Response body:   none
-Status:  204 on success, 404 if *canvID* does not exist.
-Comments:
-The JSON array in the request body should contain new values for the canvas' annotations.  If the `merge` parameter is `false`, the existing annotations will be completely replaced; if it is `true` or omitted, only annotations mentioned in the request body will be affected.

 ### Get canvas lines ###
 Endpoint:  /canvas/*canvID*/lines
 Method: GET
-Request body:  none
-Response body: \[{"id":37484,"index":0,"annotation":38042,"endOffset":46,"content":"fratres nostri quae acta sunt et quae difinita","startOffset":0,"page":2085},…]
-Status:  200 on success, 404 if *canvID* does not exist.
-Comments:
-Response contains an array with all lines found on the given canvas.  A line is actually an annotation, but with a slightly different set of fields.  The "annotation" field of the line object can be used to retrieve the full set of annotation fields.

 ### Set canvas lines ###
 Endpoint:  /canvas/*canvID*/lines
 Method: PUT
-Request body:  \[{"id":38042,"startOffset":0,"endOffset":46,"type":"line","purpose":"LB","content":"fratres nostri quae acta sunt et quae difinita","motivation":"sc:painting","canvas":2085,"bounds":{"height":50,"width":627,"y":76,"x":40},"startPage":2085,"endPage":2085},…]
-Request parameters:  `merge=true|false` (default `true`)
-Response body:  none
-Status:  204 on success, 404 if *canvID* does not exist.
-Comments:
-The JSON array in the request body should contain new values for the canvas' lines.  If the `merge` parameter is `false` the existing lines will be completely replaced; if it is `true` or omitted, only lines mentioned in the request body will be affected.  For the purposes of this endpoint, a canvas' lines are considered to be all annotations whose "purpose" is "line" and whose "canvas" is *canvID*.

 ## 9. Annotations ##
@@ -355,27 +205,14 @@
 ### Get annotation details ###
 Endpoint:  /annotation/*annID*
 Method:  GET
-Request body:  none
-Response body:  {"id":81538,"startOffset":1938,"endOffset":1938,"target":null,"selector":null,"type":"g","purpose":"NONE","content":null,"attributes":"{\"ref\":\"#slash\"}","modifiedBy":0,"approvedBy":0,"startPage":17000,"endPage":17000,"bounds":null,"canvas":null}
-Status:  200 on success, 404 if *annID* does not exist.

 ### Set annotation details ###
 Endpoint:  /annotation/*annID*
 Method: PUT
-Request body:  {"content":"/"}
-Response body:  none
-Status:  204 on success, 404 if *annID* does not exist.
-Comments:
-The JSON object in the request body should contain all fields which are to be modified; fields which aren't being changed can be omitted.

 ### Delete an annotation ###
 Endpoint:  /annotation/*annID*
 Method: DELETE
-Request body:  none
-Response body:  none
-Status:  204 on success.
-Comments:
-Deletes the single annotation identified by *annID*.

 ## 10. Collation ##
@@ -383,122 +220,17 @@
 ### Full-edition collation ###
 Endpoint:  /collation/*edID*
 Method:  GET
-Request body:  none
-Response content-type:  application/json
-Response body:  an array of arrays of mote annotations:
-\[
-   \[
-      {"content":"Lectio 1, Prologus","endOffset":18,"target":"#2","endPage":2000,"startPage":2000,"startOffset":0},
-      {"content":"Lectio 1, Prologus","endOffset":18,"target":"#1","endPage":1000,"startPage":1000,"startOffset":0}
-   ],
-   \[
-      {"content":"\[Reims","endOffset":25,"target":"#1","endPage":1000,"startPage":1000,"startOffset":19}
-   ],
-   \[
-      {"content":"\[Sorbonne","endOffset":28,"target":"#2","endPage":2000,"startPage":2000,"startOffset":19}
-   ],
-   …
-]
-Status:  200 on success, 404 if *edID* does not exist.
-Comments:  This provides a full collation of all the witnesses in the specified edition.  The response contains an array of arrays of mote annotations.  Each of the subarrays contains mote annotations which the collator has determined to be in correspondence.  The `target` field of the mote annotations is used to indicate the witness whose content provides support for the annotation.
-

 ### Sub-collation ###
 Endpoint:  /collation
 Method:  GET
-Request content-type:  application/json
-Request body:  an array of text ranges:
-\[
-   {"startPage":1000,"startOffset":0,"endPage":1000,"endOffset":477},
-   {"startPage":2000,"startOffset":0,"endPage":2000,"endOffset":360}
-]
-Response content-type:  application/json
-Response body:  an array of arrays of mote annotations:
-\[
-   \[
-      {"content":"Lectio 1, Prologus","endOffset":18,"target":"#2","endPage":2000,"startPage":2000,"startOffset":0},
-      {"content":"Lectio 1, Prologus","endOffset":18,"target":"#1","endPage":1000,"startPage":1000,"startOffset":0}
-   ],
-   \[
-      {"content":"\[Reims","endOffset":25,"target":"#1","endPage":1000,"startPage":1000,"startOffset":19}
-   ],
-   \[
-      {"content":"\[Sorbonne","endOffset":28,"target":"#2","endPage":2000,"startPage":2000,"startOffset":19}
-   ],
-   …
-]
-Status:  200 on success, 400 if the text ranges are not consistent (e.g. a range has a negative length, or refers to pages from two separate witnesses).
-Comments:  The request body must contain an array of JSON objects specifying the text ranges to be collated.  In practice, this may be an array of annotations, but that need not be the case.  The response contains an array of arrays of mote annotations.  Each of the subarrays contains mote annotations which the collator has determined to be in correspondence.  The `target` field of the mote annotations is used to indicate the witness whose content provides support for the annotation.
-

 ## 11. Config ##
 Endpoint:  /config
 Method:  GET
-Request body:  none
-Response content-type:  application/json
-Response body:  {"version":"0.9.1", "revision":189}
-Status: 200 on success.
-Comments: The response's "version" property contains the "version-num" property from `build.xml`.  The "revision" property contains the SVN revision which was used to build the WAR file.  At present, this endpoint does not require authentication.

 ## 12. Activity Log ##
-
 Endpoint:  /activity
 Method:  GET
-Parameters:  user=*userID* to retrieve activities of a given user
-table=*table*&id=*id* to retrieve activities associated with a given entity.  The `table` parameter can be one of `annotations`, `canvasses`, `decisions`, `editions`, `images`, `manifests`, `pages`, `transcriptions`, `users`, or `witnesses`.  The optional `id` parameter identifies the particular entity of that type.
-Request body:  none
-Response body:  An array of activity records:
-\[
-   {
-      "content":"Lectio 1, Prologus \[Reims Transcription]",
-      "operation":"INSERT",
-      "time":1381535382000,
-      "entity":"witness/1",
-      "parent":"edition/1",
-      "user":2
-   },
-   …
-]
-Status:  200 on success
-Comments: The endpoint returns an array of activity entries. The `operation` property can be `INSERT`, `UPDATE`, `DELETE`, or `VIEW`.  The entity which changed is identified by the `entity` property.  The time of the activity and the user responsible are specified by the `time` and `user` properties.  For insertions, there will also be a `parent` property which identifies where the newly-created entity was inserted.
-
-The `content` property describes the change that occurred.  The values are summarised in this table:
-
-operation | type      | content
---------- | --------- | -------
-INSERT    | editions  | Title of newly-created edition
-UPDATE    | editions  | JSON object containing changes sent by the client
For /editions sub-endpoints, it may be a JSON array of motes, or permissions.
-INSERT    | users     | Name of newly-created user
-UPDATE    | users     | "Account confirmed."
-INSERT    | witnesses | Title of newly-created witness
-UPDATE    | witnesses | "Witness updated."
-UPDATE    | *other*   | JSON object containing changes sent by the client
-DELETE    | *all*     | none
-
-
-## 13. T-PEN proxy ##
-
-Endpoint: /tpen?config
-Method: GET
-Request body:  none
-Response content-type:  application/json
-Response body:  {"tpen":"http://t-pen.org/TPEN"}
-Status: 200 on success.
-Comments: This method is used to retrieve the address of the T-PEN server being used by Tradamus, as configured in Tradamus' `web.xml`.
-
-
-Endpoint: /tpen
-Method: GET or POST (as appropriate)
-Comments:  Special endpoint for proxying calls to T-PEN.  The portion of the request following /tpen will be forwarded to the T-PEN instance configured in the "server" init-param entry of the Tradamus web.xml file.  Has been tested with the following T-PEN endpoints:
-
-   GET /tpen/login
-   GET /tpen/projects
-   GET /tpen/project/*projID*
-
-Authentication can be done in two ways:  by cookie or by white-list.
-
-In the cookie method, first call the T-PEN login endpoint to get a JSESSIONID cookie and pass that to subsequent calls.
-
-The white-list method depends on the Tradamus user-name (typically an email address) also existing in T-PEN.  The line TRADAMUS=*TradamusIPAddress* must be added to the T-PEN version.properties file, to tell T-PEN that requests from that Tradamus instance are allowed to bypass the usual T-PEN login process.

Endpoint Permissions modified by Eric Smith

Eric Smith — Wed, 02 Apr 2014 22:24:57 -0000

The following table describes the permission level which is required to access the given endpoint. The endpoints themselves are more full described in [Tradamus Server API].

There are five ranked levels of permissions: NONE, VIEWER, CONTRIBUTOR, EDITOR, and OWNER. If a user has a particular level of access to a resource, they also implicitly have all the lower levels of access.

Permissions can currently be set at three different points: the Edition, the Transcription, and the Manifest. When verifying

1. Users

Add new user

POST /users
No restrictions.

Invite new user

POST /users
EDITOR on associated edition.

Get user details

GET /user/userID
No restrictions.

Get user details by email

GET /user?mail=emailAddress
No restrictions.

Modify user details

PUT /user/userID
Only userID can modify their own details.

Reset user password

PUT /user?reset=emailAddress
No restrictions.

Log in to Tradamus

POST /login
No restrictions.

GET /login
The call always returns the status of the currently logged-in user.

POST /editions
GET /editions
GET /edition/edID
PUT /edition/edID
POST /edition/edID/metadata
PUT /edition/edID/metadata
GET /edition/edID/decisions
PUT /edition/edID/decisions
PUT /edition/edID/permissions
DELETE /edition/edID

POST /witnesses
Method: POST
Parameters: edition=edID (required)
Request content-type: application/json
Request body: {"title":"My Witness","siglum":"M"}
Status: 201 on success, 404 if edID does not exist.
Comments:
This allows the creation of a witness from JSON (non-LD) data. The "title" and "siglum" fields are required.

Import JSON-LD witness

Endpoint: /witnesses
Method: POST
Parameters: edition=edID (required)
Request content-type: application/ld+json
Request body: single-file IIIF metadata representation
Status: 201 on success, 404 if edID does not exist.
Comments:
Currently the only source for this type of file is the JSON-LD export from T-PEN. The IIIF metadata spec is still under development, and does not appear to yet be supported by any other software.

Import XML witness

Endpoint: /witnesses
Method: POST
Parameters: edition=edID (required)
Request content-type: text/xml
Request body: TEI XML file
Status: 201 on success, 404 if edID does not exist.
Comments:
This has so far only been tested with TEI files from Jeffrey Witt's Petrus Plaoul corpus. The implementation will need to be generalised as we encounter other TEI files.

Get witness details

Endpoint: /witness/witID
Method: GET
Request body: none
Response body:
{
  "id":4,
  "author":"Petrus Plaoul",
  "edition":1,
  "title":"Lectio 1, Prologus [Vatican Transcription]",
  "manifest":3,
  "siglum":"V",
  "transcription":3,
  "metadata":{
    "editor":"Jeffrey C. Witt",
    "pubPlace":"Boston, MA"
  }
}
Status: 200 on success, 404 if witID does not exist.
Comments:

Set witness details

Endpoint: /witness/witID
Method: PUT
Request content-type: application/json
Request body: {"author":"New Author", "title":"New Title", "siglum":"New Siglum"}
Response body: none
Status: 204 on success, 404 if witID does not exist.
Comments:
The request body should contain a JSON object describing the fields to be changed. Any fields which are omitted from the request will remain unchanged.

Add a witness metadatum

Endpoint: /witness/witID/metadata
Method: POST
Request content-type: application/json
Request body: {"type":"colour","content":"turquoise"}
Response body: none
Response location: /annotation/annID
Status: 201 on success, 404 if witID does not exist.
Comments:
The request body should contain a single annotation object. The Location header of the response gives the caller the ID of the newly-created metadatum.

Set witness metadata

Endpoint: /witness/witID/metadata
Method: PUT
Request content-type: application/json
Request body: [{"type":"colour","content":"turquoise"}]
Request parameters: merge=true|false (default true)
Response body: none
Status: 204 on success, 404 if witID does not exist.
Comments:
The request body should contain an array of annotation objects. If the merge parameter is false, the contents of the array will completely replace the witness' existing metadata; if merge is true or omitted, the PUT will only affect metadata objects included in the request body. In either case, the call will create any objects found in the request body which don't already exist.

Delete a witness

Endpoint: /witness/witID
Method: DELETE
Request body: none
Response body: none
Status: 204 on success.
Comments:
Deletes the single witness identified by witID. Associated transcriptions, pages, manifests, canvasses, images, and annotations will also be deleted.

Recursively get all witness annotations

Endpoint: /witness/witID/annotations
Method: GET
Request body: none
Response body:
Status: 200 on success, 404 if witID does not exist.
Comments:
Convenience function which aggregates the annotations from all canvasses and pages associated with the witness.

5. Transcriptions

Each witness has exactly one corresponding transcription object, which is created automatically when the witness is created. A transcription contains some metadata (e.g. the editor name), but its main purpose is to serve as a container to group together all the pages.

Get transcription details

Endpoint: /transcription/transcrID
Method: GET
Request body: none
Response body: {
  "id":1,"editor":"J. Witt",
  "pages":[
    {"id":1000,"title":"1r"},
    {"id":6001,"title":"1v"}
  ]
}
Status: 200 on success, 404 if transcrID does not exist.
Comments:
The "pages" field of the transcription object provides an array with the IDs and titles of all pages associated with said transcription.

Set transcription permissions

Endpoint: /transcription/transcrID/permissions
Method: PUT
Request content-type: application/json
Request body: [{"user":uID, "role":"OWNER"}]
Request parameters: merge=true|false (default true)
Response body: none
Status: 204 on success, 404 if transcrID does not exist, 409 if the request body refers to a nonexistent user ID.
Comments:
The request body should contains an array of user permissions objects. The "user" field of each object should contain a user ID, and the "role" field one of "NONE", "VIEWER", "CONTRIBUTOR", "EDITOR", or "OWNER", identifying the permissions that will be granted to that user for the given transcription. If the merge parameter is false, the contents of the array will completely replace the transcription's existing permissions; if it is true or omitted, only permissions mentioned in the request body will be affected.

6. Pages

Get page details

Endpoint: /page/pageID
Method: GET
Request body: none
Response body: {"id":5, "text":"Quantum ad istud…", "title":"S4r.jpg", "index":4, "transcription":1}
Status: 200 on success, 404 if pageID does not exist.
Comments:
The "index" field contains the page's index within the transcription as a whole. If the "annotations" parameter is specified, the response will include an array of all annotation objects attached to the page. Similarly, specifying the "lines" parameter will include an array of all line objects.

Set page details

Endpoint: /page/pageID
Method: PUT
Request body: {"id":5, "text":"Quantum ad istud…"}
Response body: none
Status: 204 on success, 404 if pageID does not exist.
Comments:
The JSON object in the request body should contain all fields which are to be modified; fields which aren't being changed can be omitted. Changing the page's "text" property may result in annotations being recalculated. Changing the page's "index" property can be used to reorder pages within the transcription.

Add a page annotation

Endpoint: /page/pgID/annotations
Method: POST
Request content-type: application/json
Request body: {"type":"colour","content":"turquoise"}
Response body: none
Response location: /annotation/annID
Status: 201 on success, 404 if pgID does not exist.
Comments:
The request body should contain a single annotation object. The Location header of the response gives the caller the ID of the newly-created annotation.

Get page annotations

Endpoint: /page/pgID/annotations
Method: GET
Request body: none
Response body: [{"id":38042,"startOffset":0,"endOffset":46,"type":"line","purpose":"LB","content":"fratres nostri quae acta sunt et quae difinita","motivation":"sc:painting","canvas":2085,"bounds":{"height":50,"width":627,"y":76,"x":40},"startPage":2085,"endPage":2085},…]
Status: 200 on success, 404 if pgID does not exist.
Comments:
Response contains an array with all annotations found on the given page. This includes multi-page annotations whose page range includes the page in question. Since lines are annotations, they will be included in the response.

Set page annotations

Endpoint: /page/pageID/annotations
Method: PUT
Request body: [{"id":38042,"startOffset":0,"endOffset":46,"type":"line","purpose":"LB","content":"fratres nostri quae acta sunt et quae difinita","motivation":"sc:painting","canvas":2085,"bounds":{"height":50,"width":627,"y":76,"x":40},"startPage":2085,"endPage":2085},…]
Request parameters: merge=true|false (default true)
Response body: none
Status: 204 on success, 404 if pageID does not exist.
Comments:
The JSON array in the request body should contain new values for the page's annotations. If the merge parameter is false, the existing annotations will be completely replaced; if it is true or omitted, only annotations mentioned in the request body will be affected. For the purposes of this endpoint, a page's annotations are considered to be all annotations whose "startPage" to "endPage" range includes pageID.

Get page lines

Endpoint: /page/pgID/lines
Method: GET
Request body: none
Response body: [
{"id":34796,"startOffset":0,"endOffset":55,"selector":null,"type":"line","purpose":"LB","content":"episcopum fuisse aut esse neque ipsos qui ab eo ordina-","attributes":null,"startPage":6118,"endPage":6118,"bounds":{"height":94,"width":662,"y":9,"x":53},"canvas":6118},
…
]
Status: 200 on success, 404 if pgID does not exist.
Comments:
Response contains an array with all line annotations found on the given page.

Set page lines

Endpoint: /page/pageID/lines
Method: PUT
Request body: [{"id":38042,"startOffset":0,"endOffset":46,"type":"line","purpose":"LB","content":"fratres nostri quae acta sunt et quae difinita","motivation":"sc:painting","canvas":2085,"bounds":{"height":50,"width":627,"y":76,"x":40},"startPage":2085,"endPage":2085},…]
Request parameters: merge=true|false (default true)
Response body: none
Status: 204 on success, 404 if pageID does not exist.
Comments:
The JSON array in the request body should contain new values for the page's lines. If the merge parameter is false, the existing lines will be completely replaced; if it is true or omitted, only lines mentioned in the request body will be affected. For the purposes of this endpoint, a page's lines are considered to be all annotations whose "purpose" is "LB" and whose "startPage" is pageID.

7. Manifests

Each witness has exactly one corresponding manifest object, which is created automatically when the witness is created. A manifest will eventually contain some metadata, but its main purpose is to serve as a container to group together all the canvasses.

Get manifest details

Endpoint: /manifest/manID
Method: GET
Request body: none
Response body: {"id":3,"canvasses":[9,10,11,12]}
Status: 200 on success, 404 if manID does not exist.
Comments:
The "canvasses" field of the manifest object provides an array with the IDs of all canvasses associated with said manifest.

Set manifest permissions

Endpoint: /manifest/manID/permissions
Method: PUT
Request content-type: application/json
Request body: [{"user":uID, "role":"OWNER"}]
Request parameters: merge=true|false (default true)
Response body: none
Status: 204 on success, 404 if manID does not exist, 409 if the request body refers to a nonexistent user ID.
Comments:
The request body should contains an array of user permissions objects. The "user" field of each object should contain a user ID, and the "role" field one of "NONE", "VIEWER", "CONTRIBUTOR", "EDITOR", or "OWNER", identifying the permissions that will be granted to that user for the given manifest. If the merge parameter is false, the contents of the array will completely replace the manifest's existing permissions; if it is true or omitted, only permissions mentioned in the request body will be affected.

8. Canvasses

Get canvas details

Endpoint: /canvas/canvID
Method: GET
Request body: none
Response body: {"id":12,"title":"R2v.jpg","page":12,"manifest":3}
Status: 200 on success, 404 if canvID does not exist.
Comments:
The "index" field contains the canvas' index within the manifest as a whole.

Set canvas details

Endpoint: /canvas/canvID
Method: PUT
Request body: {"id":5,"title":"Frontispiece"}
Response body: none
Status: 204 on success, 404 if canvID does not exist.
Comments:
The JSON object in the request body should contain all fields which are to be modified; fields which aren't being changed can be omitted. Changing the canvas' "index" property can be used to reorder canvasses within the manifest.

Add a canvas annotation

Endpoint: /canvas/canvID/annotations
Method: POST
Request content-type: application/json
Request body: {"type":"colour","content":"turquoise"}
Response body: none
Response location: /annotation/annID
Status: 201 on success, 404 if canvID does not exist.
Comments:
The request body should contain a single annotation object. The Location header of the response gives the caller the ID of the newly-created annotation.

Get canvas annotations

Endpoint: /canvas/canvID/annotations
Method: GET
Request body: none
Response body: [{"id":36748,"startOffset":0,"endOffset":58,"type":"line","purpose":"LB","content":"de adulterio accussant et non habent latentia peccata uin-","motivation":"sc:painting","canvas":2033,"bounds":{"height":66,"width":601,"y":64,"x":31},"startPage":2033,"endPage":2033},…]
Status: 200 on success, 404 if canvID does not exist.
Comments:
Response contains an array with all annotations found on the given canvas. Since lines are annotations, they will be included in the response.

Set canvas annotations

Endpoint: /canvas/canvID/annotations
Method: PUT
Request body: [{"id":38042,"startOffset":0,"endOffset":46,"type":"line","purpose":"LB","content":"fratres nostri quae acta sunt et quae difinita","motivation":"sc:painting","canvas":2085,"bounds":{"height":50,"width":627,"y":76,"x":40},"startPage":2085,"endPage":2085},…]
Request parameters: merge=true|false (default true)
Response body: none
Status: 204 on success, 404 if canvID does not exist.
Comments:
The JSON array in the request body should contain new values for the canvas' annotations. If the merge parameter is false, the existing annotations will be completely replaced; if it is true or omitted, only annotations mentioned in the request body will be affected.

Get canvas lines

Endpoint: /canvas/canvID/lines
Method: GET
Request body: none
Response body: [{"id":37484,"index":0,"annotation":38042,"endOffset":46,"content":"fratres nostri quae acta sunt et quae difinita","startOffset":0,"page":2085},…]
Status: 200 on success, 404 if canvID does not exist.
Comments:
Response contains an array with all lines found on the given canvas. A line is actually an annotation, but with a slightly different set of fields. The "annotation" field of the line object can be used to retrieve the full set of annotation fields.

Set canvas lines

Endpoint: /canvas/canvID/lines
Method: PUT
Request body: [{"id":38042,"startOffset":0,"endOffset":46,"type":"line","purpose":"LB","content":"fratres nostri quae acta sunt et quae difinita","motivation":"sc:painting","canvas":2085,"bounds":{"height":50,"width":627,"y":76,"x":40},"startPage":2085,"endPage":2085},…]
Request parameters: merge=true|false (default true)
Response body: none
Status: 204 on success, 404 if canvID does not exist.
Comments:
The JSON array in the request body should contain new values for the canvas' lines. If the merge parameter is false the existing lines will be completely replaced; if it is true or omitted, only lines mentioned in the request body will be affected. For the purposes of this endpoint, a canvas' lines are considered to be all annotations whose "purpose" is "line" and whose "canvas" is canvID.

9. Annotations

Get annotation details

Endpoint: /annotation/annID
Method: GET
Request body: none
Response body: {"id":81538,"startOffset":1938,"endOffset":1938,"target":null,"selector":null,"type":"g","purpose":"NONE","content":null,"attributes":"{\"ref\":\"#slash\"}","modifiedBy":0,"approvedBy":0,"startPage":17000,"endPage":17000,"bounds":null,"canvas":null}
Status: 200 on success, 404 if annID does not exist.

Set annotation details

Endpoint: /annotation/annID
Method: PUT
Request body: {"content":"/"}
Response body: none
Status: 204 on success, 404 if annID does not exist.
Comments:
The JSON object in the request body should contain all fields which are to be modified; fields which aren't being changed can be omitted.

Delete an annotation

Endpoint: /annotation/annID
Method: DELETE
Request body: none
Response body: none
Status: 204 on success.
Comments:
Deletes the single annotation identified by annID.

10. Collation

Full-edition collation

Endpoint: /collation/edID
Method: GET
Request body: none
Response content-type: application/json
Response body: an array of arrays of mote annotations:
[
   [
      {"content":"Lectio 1, Prologus","endOffset":18,"target":"#2","endPage":2000,"startPage":2000,"startOffset":0},
      {"content":"Lectio 1, Prologus","endOffset":18,"target":"#1","endPage":1000,"startPage":1000,"startOffset":0}
   ],
   [
      {"content":"[Reims","endOffset":25,"target":"#1","endPage":1000,"startPage":1000,"startOffset":19}
   ],
   [
      {"content":"[Sorbonne","endOffset":28,"target":"#2","endPage":2000,"startPage":2000,"startOffset":19}
   ],
   …
]
Status: 200 on success, 404 if edID does not exist.
Comments: This provides a full collation of all the witnesses in the specified edition. The response contains an array of arrays of mote annotations. Each of the subarrays contains mote annotations which the collator has determined to be in correspondence. The target field of the mote annotations is used to indicate the witness whose content provides support for the annotation.

Sub-collation

Endpoint: /collation
Method: GET
Request content-type: application/json
Request body: an array of text ranges:
[
   {"startPage":1000,"startOffset":0,"endPage":1000,"endOffset":477},
   {"startPage":2000,"startOffset":0,"endPage":2000,"endOffset":360}
]
Response content-type: application/json
Response body: an array of arrays of mote annotations:
[
   [
      {"content":"Lectio 1, Prologus","endOffset":18,"target":"#2","endPage":2000,"startPage":2000,"startOffset":0},
      {"content":"Lectio 1, Prologus","endOffset":18,"target":"#1","endPage":1000,"startPage":1000,"startOffset":0}
   ],
   [
      {"content":"[Reims","endOffset":25,"target":"#1","endPage":1000,"startPage":1000,"startOffset":19}
   ],
   [
      {"content":"[Sorbonne","endOffset":28,"target":"#2","endPage":2000,"startPage":2000,"startOffset":19}
   ],
   …
]
Status: 200 on success, 400 if the text ranges are not consistent (e.g. a range has a negative length, or refers to pages from two separate witnesses).
Comments: The request body must contain an array of JSON objects specifying the text ranges to be collated. In practice, this may be an array of annotations, but that need not be the case. The response contains an array of arrays of mote annotations. Each of the subarrays contains mote annotations which the collator has determined to be in correspondence. The target field of the mote annotations is used to indicate the witness whose content provides support for the annotation.

11. Config

Endpoint: /config
Method: GET
Request body: none
Response content-type: application/json
Response body: {"version":"0.9.1", "revision":189}
Status: 200 on success.
Comments: The response's "version" property contains the "version-num" property from build.xml. The "revision" property contains the SVN revision which was used to build the WAR file. At present, this endpoint does not require authentication.

12. Activity Log

Endpoint: /activity
Method: GET
Parameters: user=userID to retrieve activities of a given user
table=table&id=id to retrieve activities associated with a given entity. The table parameter can be one of annotations, canvasses, decisions, editions, images, manifests, pages, transcriptions, users, or witnesses. The optional id parameter identifies the particular entity of that type.
Request body: none
Response body: An array of activity records:
[
   {
      "content":"Lectio 1, Prologus [Reims Transcription]",
      "operation":"INSERT",
      "time":1381535382000,
      "entity":"witness/1",
      "parent":"edition/1",
      "user":2
   },
   …
]
Status: 200 on success
Comments: The endpoint returns an array of activity entries. The operation property can be INSERT, UPDATE, DELETE, or VIEW. The entity which changed is identified by the entity property. The time of the activity and the user responsible are specified by the time and user properties. For insertions, there will also be a parent property which identifies where the newly-created entity was inserted.

The content property describes the change that occurred. The values are summarised in this table:

operation	type	content
INSERT	editions	Title of newly-created edition
UPDATE	editions	JSON object containing changes sent by the client For /editions sub-endpoints, it may be a JSON array of motes, or permissions.
INSERT	users	Name of newly-created user
UPDATE	users	"Account confirmed."
INSERT	witnesses	Title of newly-created witness
UPDATE	witnesses	"Witness updated."
UPDATE	other	JSON object containing changes sent by the client
DELETE	all	none

13. T-PEN proxy

Endpoint: /tpen?config
Method: GET
Request body: none
Response content-type: application/json
Response body: {"tpen":"http://t-pen.org/TPEN"}
Status: 200 on success.
Comments: This method is used to retrieve the address of the T-PEN server being used by Tradamus, as configured in Tradamus' web.xml.

Endpoint: /tpen
Method: GET or POST (as appropriate)
Comments: Special endpoint for proxying calls to T-PEN. The portion of the request following /tpen will be forwarded to the T-PEN instance configured in the "server" init-param entry of the Tradamus web.xml file. Has been tested with the following T-PEN endpoints:

   GET /tpen/login
   GET /tpen/projects
   GET /tpen/project/projID

Authentication can be done in two ways: by cookie or by white-list.

In the cookie method, first call the T-PEN login endpoint to get a JSESSIONID cookie and pass that to subsequent calls.

The white-list method depends on the Tradamus user-name (typically an email address) also existing in T-PEN. The line TRADAMUS=TradamusIPAddress must be added to the T-PEN version.properties file, to tell T-PEN that requests from that Tradamus instance are allowed to bypass the usual T-PEN login process.