Recent changes to EditionAPI

EditionAPI modified by Domhnall101

Domhnall101 — Tue, 06 Oct 2015 19:44:45 -0000

--- v19
+++ v20
@@ -1,10 +1,11 @@
 Draft 2015-06-09
-
-## 1. Editions ##
+##Edition API
+
+### 1. Editions ##

 Editions are created by POSTing JSON data to the /editions endpoint.  The list of editions can be retrieved by a GET request to the /editions endpoint.

-### Add new edition ###
+#### Add new edition ###
 Endpoint: /editions
 Method: POST
 Request content-type: application/json
@@ -15,7 +16,7 @@
 Comments:
 Requires valid JSESSIONID cookie to get the ID of the logged in user.  This will be stored as the edition's creator field.

-### List editions ###
+####List editions ###
 Endpoint: /editions
 Method: GET
 Request body:  none
@@ -24,7 +25,7 @@
 Comments:
 Retrieves an array of all edition IDs and titles which for which the logged-in user has at least VIEWER permission.  The GET /edition/*edID* endpoint can then be used to retrieve the details of that edition.

-### Get edition details ###
+#### Get edition details ###
 Endpoint: /edition/*edID*
 Method: GET
 Request body:  none
@@ -47,7 +48,7 @@
 Comments:
 The response's "creator" field contains a user ID.  The "witnesses" field contains an array of witness information for this edition.  The "permissions" field contains an array of all permissions associated with the edition.  The "outlines" field contains an array of all outlines associated with this edition.

-### Set edition details ###
+#### Set edition details ###
 Endpoint:  /edition/*edID*
 Method:  PUT
 Request content-type:  application/json
@@ -57,7 +58,7 @@
 Comments:
 The request body should contain a JSON object describing the fields to be changed.  Currently, the only valid field is "title", but this may change.

-### Add an edition metadatum ###
+#### Add an edition metadatum ###
 Endpoint: /edition/*edID*/metadata
 Method: POST
 Request content-type: application/json
@@ -68,7 +69,7 @@
 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 edition metadata ###
+#### Set edition metadata ###
 Endpoint: /edition/*edID*/metadata
 Method: PUT
 Request content-type: application/json
@@ -79,7 +80,7 @@
 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 edition's existing metadata; if `merge=true`, 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.

-### Approve edition metadata ###
+#### Approve edition metadata ###
 Endpoint: /edition/*edID*/approval
 Method: PUT
 Request content-type: application/json
@@ -89,7 +90,7 @@
 Comments:
 Sets the `approvedBy` field of the edition's metadata to the ID of the current user.  If the request body contains an array of annotation IDs, only those annotations will be marked as approved.  If the request body is absent, all the edition's metadata will be approved.

-### Add edition outline ###
+#### Add edition outline ###
 Endpoint: /edition/*edID*/outlines
 Method: POST
 Request content-type: application/json
@@ -119,7 +120,7 @@
 Comments:
 Creates a new outline associated with the given edition.  The "title" field is optional.  The "index" field indicates the outline's index relative to the edition's other outlines, and defaults to 0 if omitted.  The "bounds" field specifies the collation ranges which were used as the basis for the outline, and should be `null` for a full-edition collation.  The "decisions" field contains an initial set of decisions made by the user; this field can be an empty array if the user has not yet made any decisions.

-### Set edition outlines ###
+#### Set edition outlines ###
 Endpoint: /edition/*edID/outlines
 Method: PUT
 Request content-type: application/json
@@ -127,7 +128,7 @@
 Response body: none
 Comments: Use this method to update all outlines associated with the edition.  Useful for doing large-scale reorderings.

-### Set edition permissions ###
+#### Set edition permissions ###
 Endpoint:  /edition/*edID*/permissions
 Method:  PUT
 Request content-type:  application/json
@@ -138,7 +139,7 @@
 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 edition.  Specify `"user":0` to set permissions for the "public sharing" user.  If the `merge` parameter is `false`, the contents of the array will completely replace the edition's existing permissions; if it is `true` or omitted, only permissions mentioned in the request body will be affected.

-### Delete an edition ###
+#### Delete an edition ###
 Endpoint:  /edition/*edID*
 Method: DELETE
 Request body:  none
@@ -148,11 +149,11 @@
 Deletes the single edition identified by *edID*.  Associated witnesses, transcriptions, pages, manifests, canvasses, images, outlines, parallels, and annotations will also be deleted.

-## 2. Witnesses ##
+### 2. Witnesses ##

 Witnesses are created by posting JSON, JSON-LD or XML data to an edition's `witnesses` endpoint.  The list of witnesses can be retrieved by a GET request to the edition's `witnesses` endpoint.

-### Create a new witness using JSON ###
+#### Create a new witness using JSON ###
 Endpoint: /edition/*edID*/witnesses
 Method: POST
 Parameters: none
@@ -162,7 +163,7 @@
 Comments:
 This allows the creation of a witness from JSON (non-LD) data.  The "title" and "siglum" fields are required.

-### Import JSON-LD witness ###
+#### Import JSON-LD witness ###
 Endpoint: /edition/*edID*/witnesses
 Method: POST
 Request content-type: application/ld+json
@@ -171,7 +172,7 @@
 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.

-### Link JSON-LD witness from T-PEN ###
+#### Link JSON-LD witness from T-PEN ###
 Endpoint: /edition/*edID*/witnesses
 Method: POST
 Parameters: `src` URL of JSON-LD source (i.e. T-PEN project)
@@ -181,7 +182,7 @@
 Comments:
 This differs from importing a JSON-LD witness because the call creates a persistent link to T-PEN which is checked for updates every time the user logs in.

-### Import XML witness ###
+#### Import XML witness ###
 Endpoint: /edition/*edID*/witnesses
 Method: POST
 Request content-type: text/xml
@@ -190,7 +191,7 @@
 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.

-### Import plain text witness ###
+#### Import plain text witness ###
 Endpoint: /edition/*edID*/witnesses
 Method: POST
 Parameters:
@@ -204,7 +205,7 @@
 Comments:

-### Get witness details ###
+#### Get witness details ###
 Endpoint:  /witness/*witID*
 Method: GET
 Request body:  none
@@ -225,7 +226,7 @@
 Status:  200 on success, 404 if *witID* does not exist.
 Comments:

-### Set witness details ###
+#### Set witness details ###
 Endpoint:  /witness/*witID*
 Method:  PUT
 Request content-type:  application/json
@@ -235,7 +236,7 @@
 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 ###
+#### Add a witness metadatum ###
 Endpoint: /witness/*witID*/metadata
 Method: POST
 Request content-type: application/json
@@ -246,7 +247,7 @@
 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 ###
+#### Set witness metadata ###
 Endpoint: /witness/*witID*/metadata
 Method: PUT
 Request content-type: application/json
@@ -257,7 +258,7 @@
 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.

-### Approve witness metadata ###
+#### Approve witness metadata ###
 Endpoint: /witness/*witID*/approval
 Method: PUT
 Request content-type: application/json
@@ -267,7 +268,7 @@
 Comments:
 Sets the `approvedBy` field of the witness' metadata to the ID of the current user.  If the request body contains an array of annotation IDs, only those annotations will be marked as approved.  If the request body is absent, all the witness' metadata will be approved.

-### Delete a witness ###
+#### Delete a witness ###
 Endpoint:  /witness/*witID*
 Method: DELETE
 Request body:  none
@@ -276,7 +277,7 @@
 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 ###
+#### Recursively get all witness annotations ###
 Endpoint:  /witness/*witID*/annotations
 Method: GET
 Request body:  none
@@ -286,11 +287,11 @@
 Convenience function which aggregates the annotations from all canvasses and pages associated with the witness.

-## 3. Transcriptions ##
+### 3. 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 ###
+#### Get transcription details ###
 Endpoint:  /transcription/*transcrID*
 Method: GET
 Request body:  none
@@ -305,7 +306,7 @@
 Comments:
 The "pages" field of the transcription object provides an array with the IDs and titles of all pages associated with said transcription.

-### Add a transcription annotation ###
+#### Add a transcription annotation ###
 Endpoint: /transcription/*transcrID*/annotations
 Method: POST
 Request content-type: application/json
@@ -316,7 +317,7 @@
 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 transcription pages ###
+#### Get transcription pages ###
 Endpoint: /transcription/*transcrID*/pages
 Method: GET
 Request body: none
@@ -325,7 +326,7 @@
 Comments:
 The response body will be an array containing all the pages belonging to this transcription.  The format will be the same as that returned by a GET request to /page/*pgID*.

-### Set transcription permissions ###
+#### Set transcription permissions ###
 Endpoint:  /transcription/*transcrID*/permissions
 Method:  PUT
 Request content-type:  application/json
@@ -337,9 +338,9 @@
 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.  Specify `"user":0` to set permissions for the "public sharing" user.  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.

-## 4. Pages ##
-
-### Get page details ###
+### 4. Pages ##
+
+#### Get page details ###
 Endpoint:  /page/*pageID*
 Method: GET
 Request body:  none
@@ -348,7 +349,7 @@
 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 ###
+#### Set page details ###
 Endpoint:  /page/*pageID*
 Method: PUT
 Request body:  {"id":5, "text":"Quantum ad istud…"}
@@ -357,7 +358,7 @@
 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 ###
+#### Add a page annotation ###
 Endpoint: /page/*pgID*/annotations
 Method: POST
 Request content-type: application/json
@@ -368,7 +369,7 @@
 Comments:
 The request body should contain a single annotation object.  The annotation will be constrained so that it's `startPage` and `endPage` are both equal to *pgID* (to add an annotation which spans multiple pages, use the /transcription/*transcrID/annotations endpoint instead).  The Location header of the response gives the caller the ID of the newly-created annotation.

-### Get page annotations ###
+#### Get page annotations ###
 Endpoint:  /page/*pgID*/annotations
 Method: GET
 Request body:  none
@@ -377,7 +378,7 @@
 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 ###
+#### Set page annotations ###
 Endpoint:  /page/*pgID*/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},…]
@@ -387,7 +388,7 @@
 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 *pgID*.

-### Get page lines ###
+#### Get page lines ###
 Endpoint:  /page/*pgID*/lines
 Method: GET
 Request body:  none
@@ -399,7 +400,7 @@
 Comments:
 Response contains an array with all line annotations found on the given page.

-### Set page lines ###
+#### 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},…]
@@ -410,11 +411,11 @@
 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*.

-## 5. Manifests ##
+### 5. 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 ###
+#### Get manifest details ###
 Endpoint:  /manifest/*manID*
 Method:  GET
 Request body:  none
@@ -423,7 +424,7 @@
 Comments:
 The "canvasses" field of the manifest object provides an array with the IDs of all canvasses associated with said manifest.

-### Add a manifest annotation ###
+#### Add a manifest annotation ###
 Endpoint: /manifest/*manID*/annotations
 Method: POST
 Request content-type: application/json
@@ -434,7 +435,7 @@
 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 manifest canvasses ###
+#### Get manifest canvasses ###
 Endpoint: /manifest/*manID*/canvasses
 Method: GET
 Request body: none
@@ -444,7 +445,7 @@
 The response body will be an array containing all the canvasses belonging to this manifest.  The format will be the same as that returned by a GET request to /canvas/*canvID*.

-### Set manifest permissions ###
+#### Set manifest permissions ###
 Endpoint:  /manifest/*manID*/permissions
 Method:  PUT
 Request content-type:  application/json
@@ -456,9 +457,9 @@
 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.  Specify `"user":0` to set permissions for the "public sharing" user.  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.

-## 6. Canvasses ##
-
-### Get canvas details ###
+### 6. Canvasses ##
+
+#### Get canvas details ###
 Endpoint:  /canvas/*canvID*
 Method:  GET
 Request body:  none
@@ -467,7 +468,7 @@
 Comments:
 The "index" field contains the canvas' index within the manifest as a whole.  For convenience, the response body also contains the canvas' "images" array.

-### Set canvas details ###
+#### Set canvas details ###
 Endpoint:  /canvas/*canvID*
 Method: PUT
 Request body:  {"id":5,"title":"Frontispiece"}
@@ -476,7 +477,7 @@
 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 ###
+#### Add a canvas annotation ###
 Endpoint: /canvas/*canvID*/annotations
 Method: POST
 Request content-type: application/json
@@ -487,7 +488,7 @@
 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 ###
+#### Get canvas annotations ###
 Endpoint:  /canvas/*canvID*/annotations
 Method:  GET
 Request body:  none
@@ -496,7 +497,7 @@
 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 ###
+#### 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},…]
@@ -506,7 +507,7 @@
 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.

-### Set canvas images ###
+#### Set canvas images ###
 Endpoint:  /canvas/*canvID*/images
 Method: PUT
 Request body:  \[{"id":2,"index":0,"uri":"http://localhost:8080/TPEN/imageResize?folioNum=12841944&height=1000&user=ericsmith@slu.edu","format":"JPEG","width":1472,"height":2000,"canvas":1001},…]
@@ -516,7 +517,7 @@
 Comments:
 The JSON array in the request body should contain new values for the canvas' images.  If the `merge` parameter is `false`, the existing images will be completely replaced; if it is `true` or omitted, only images mentioned in the request body will be affected.

-### Get canvas lines ###
+#### Get canvas lines ###
 Endpoint:  /canvas/*canvID*/lines
 Method: GET
 Request body:  none
@@ -525,7 +526,7 @@
 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 ###
+#### 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},…]
@@ -536,9 +537,9 @@
 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*.

-## 7. Images ##
-
-### Get an image ###
+### 7. Images ##
+
+#### Get an image ###
 Endpoint: /image/*imgID*
 Method: GET
 Request body: none
@@ -547,23 +548,23 @@
 Comments: Retrieves the given image.  If the image's `uri` field corresponds to a known repository, the image data will be fetched using the T-PEN proxy mechanism.  Otherwise, the request will be redirected to the location given in the `uri` field.

-## 8. Outlines ##
-
-### Get outline details ###
+### 8. Outlines ##
+
+#### Get outline details ###
 Endpoint: /outline/*outlID*
 Method: GET
 Request body: none
 Response body: an [Outline](../Edition API Structures#Outline)
 Status: 200 on success.

-### Set outline details ###
+#### Set outline details ###
 Endpoint: /outline/*outlID*
 Method: PUT
 Request body: an [Outline](../Edition API Structures#Outline)
 Response body: none
 Status: 200 on success.

-### Delete an outline ###
+#### Delete an outline ###
 Endpoint:  /outline/*outlID*
 Method: DELETE
 Request body:  none
@@ -572,7 +573,7 @@
 Comments:
 Deletes the single outline identified by *outlID*.

-### Approve outline decisions ###
+#### Approve outline decisions ###
 Endpoint: /outline/*outlID*/approval
 Method: PUT
 Request content-type: application/json

EditionAPI modified by Domhnall101

Domhnall101 — Tue, 06 Oct 2015 19:40:57 -0000

Edition API modified by Eric Smith

Eric Smith — Tue, 09 Jun 2015 20:40:09 -0000

--- v17
+++ v18
@@ -1,4 +1,4 @@
-Draft 2015-06-04
+Draft 2015-06-09

 ## 1. Editions ##

@@ -536,7 +536,18 @@
 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*.

-## 7. Outlines ##
+## 7. Images ##
+
+### Get an image ###
+Endpoint: /image/*imgID*
+Method: GET
+Request body: none
+Response body: Image data (usually image/jpeg).
+Status: 200 if image is from a known T-PEN repository, 302 if not.
+Comments: Retrieves the given image.  If the image's `uri` field corresponds to a known repository, the image data will be fetched using the T-PEN proxy mechanism.  Otherwise, the request will be redirected to the location given in the `uri` field.
+
+
+## 8. Outlines ##

 ### Get outline details ###
 Endpoint: /outline/*outlID*

Edition API modified by Eric Smith

Eric Smith — Thu, 04 Jun 2015 17:27:57 -0000

--- v16
+++ v17
@@ -1,4 +1,4 @@
-Draft 2015-05-27
+Draft 2015-06-04

 ## 1. Editions ##

@@ -536,45 +536,7 @@
 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*.

-## 7. 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.
-
-### Approve an annotation ###
-Endpoint: /annotation/*annID*/approval
-Method: PUT
-Request body: none
-Response body: none
-Status: 204 on success, 403 if the user does not have `EDITOR` permission on *annID*, 404 if *annID* does not exist.
-Comments:
-Sets the `approvedBy` field of the annotation to the ID of the current user.
-
-
-### 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*.
-
-
-## 8. Outlines ##
+## 7. Outlines ##

 ### Get outline details ###
 Endpoint: /outline/*outlID*
@@ -608,88 +570,3 @@
 Status: 204 on success, 403 if the user does not have `EDITOR` permission on *outlID*, 404 if *outlID* does not exist.
 Comments:
 Sets the `approvedBy` field of the outline's decisions to the ID of the current user.  If the request body contains an array of annotation IDs, only those annotations will be marked as approved.  If the request body is absent, all the outline's decisions will be approved.
-
-
-## 9. Collation ##
-
-Invokes the CollateX engine to generate a comparison of the specified witnesses.  CollateX is invoked with the Needleman-Wunsch algorithm.  The details of the collation can be controlled using the parameters described here:
-
-parameter         | value      | effect
------------------ | ---------- | -------
-comparison        | plain      | Witnesses are compared using just their text content.
-comparison        | morph      | Witnesses are compared based on their morphological content, using analysis performed by the Perseus morphology engine.
-comparison        | orth       | Witnesses are compared in an orthographically-aware manner, taking into account common spelling irregularities.  The `dict` parameter can be specified, to indicate the spelling dictionary to be used.
-dict              | lat        | Specifies a spelling dictionary to be used for `orth` comparison.  May be specified multiple times to use multiple spelling dictionaries.
-ignoreCase        | true       | Upper/lower case differences are ignored.
-ignoreCase        | false      | Upper/lower case differences are considered significant.
-ignoreLineBreaks  | true       | The collator ignores line-breaks and hyphenation.
-ignoreLineBreaks  | hyphens    | The collator ignores line-breaks which immediately follow a hyphen.
-ignoreLineBreaks  | false      | The collator considers line-breaks as ordinary white-space.
-ignorePunctuation | true       | Punctuation differences are ignored.
-ignorePunctuation | false      | Punctuation differences are considered significant.
-useTEITags        | true       | Embedded TEI editorial tags (e.g those from [§3.4 Simple Editorial Changes](http://www.tei-c.org/release/doc/tei-p5-doc/en/html/CO.html#COED)) are applied to the content before making the comparison.
-useTEITags        | false      | No special treatment for embedded TEI tags.
-
-### Full-edition collation ###
-Endpoint:  /collation/*edID*
-Method:  POST
-Request body:  none
-Request parameters:
-`comparison=plain|morph|orth` (default `plain`)
-`dict=`*dictionary* (default `lat`; may be specified multiple times)
-`ignoreCase=true|false` (default `false`)
-`ignoreLineBreaks=true|hyphens|false` (default `false`)
-`ignorePunctuation=true|false` (default `false`)
-`useTEITags=true|false` (default `false`)
-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,"type":"tr-mote"},
-      {"content":"Lectio 1, Prologus","endOffset":18,"target":"#1","endPage":1000,"startPage":1000,"startOffset":0,"type":"tr-mote"}
-   ],
-   \[
-      {"content":"\[Reims","endOffset":25,"target":"#1","endPage":1000,"startPage":1000,"startOffset":19,"type":"tr-mote"}
-   ],
-   \[
-      {"content":"\[Sorbonne","endOffset":28,"target":"#2","endPage":2000,"startPage":2000,"startOffset":19,"type":"tr-mote"}
-   ],
-   …
-]
-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:  POST
-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}
-]
-Request parameters:
-`comparison=text|morph|orth` (default `text`)
-`dict=`*dictionary* (default `lat`; may be specified multiple times)
-`ignoreCase=true|false` (default `false`)
-`ignoreLineBreaks=true|hyphens|false` (default `false`)
-`ignorePunctuation=true|false` (default `false`)
-`useTEITags=true|false` (default `false`)
-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,"type":"tr-mote"},
-      {"content":"Lectio 1, Prologus","endOffset":18,"target":"#1","endPage":1000,"startPage":1000,"startOffset":0,"type":"tr-mote"}
-   ],
-   \[
-      {"content":"\[Reims","endOffset":25,"target":"#1","endPage":1000,"startPage":1000,"startOffset":19,"type":"tr-mote"}
-   ],
-   \[
-      {"content":"\[Sorbonne","endOffset":28,"target":"#2","endPage":2000,"startPage":2000,"startOffset":19,"type":"tr-mote"}
-   ],
-   …
-]
-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.

Edition API modified by Eric Smith

Eric Smith — Wed, 27 May 2015 22:37:17 -0000

--- v15
+++ v16
@@ -1,114 +1,6 @@
-Draft 2015-04-23
-
-## 1. Users ##
-
-Users are created by POSTing JSON data to the /users endpoint.  Information about a particular user can be retrieved by a get request to /user/*userID*.
-
-### Add new user ###
-Endpoint: /users
-Method: POST
-Request content-type: application/json
-Request body: { "mail" : "*emailAddress*", "name" : "*fullName*", "password" : "*password*" }
-Response location: /user/*userID*
-Response body: none
-Status: 201 on success, 409 if email address already in use.
-Comments:
-The newly-registered user will be sent an email, which requires them to click a link to confirm their registration.  The user's `creation` and `last_login` fields will be set to the current time.
-
-### Invite new user ###
-Endpoint: /users
-Method: POST
-Request content-type: application/json
-Request body: { "mail" : "*emailAddress*", "name" : "*fullName*", "edition" : *editionID* }
-Response location: /user/*userID*
-Response body: none
-Status: 201 on success, 409 if email address already in use.
-Comments:
-The invitee will receive an email indicating that they have been invited by the current user (i.e. the one whose session invoked the endpoint) to work on the given edition.  The email provides a temporary randomly-generated password, as well as a link which has to be clicked to activate the new account.  The new user's `creation` field will be set to the current time, but their `last_login` field will be left as NULL.  The new user will be granted `CONTRIBUTOR` access to the edition; it is up to the edition's owner to upgrade their access if so desired.
-
-### Get user details ###
-Endpoint: /user/*userID*
-Method: GET
-Request body: none
-Response content-type: application/json
-Response body: {"id":1,"mail":"ericsmith@slu.edu","name":"Eric Smith","disabled":false,"creation":1372884249000,"lastLogin":1372885349000}
-Status: 200 on success, 401 if not logged in, 404 if user not found.
-Comments:
-Returns a JSON object providing details about the requested user.
-
-### Get user details by email ###
-Endpoint: /user?mail=*emailAddress*
-Method: GET
-Request body: none
-Response content-type: application/json
-Response body: {"id":1,"mail":"ericsmith@slu.edu","name":"Eric Smith","disabled":false,"creation":1372884249000,"lastLogin":1372885349000}
-Response location:  /user/*userID*
-Status: 200 on success, 401 if not logged in, 404 if user not found.
-Comments:
-Returns a JSON object providing details about the requested user.
-
-### Modify user details ###
-Endpoint: /user/*userID*
-Method: PUT
-Request content-type: application/json
-Request body (all fields optional) { "mail" : "*emailAddress*", "name" : "*fullName*", "password" : "*password*" }
-Response body: none
-Status: 204 on success, 401 if not logged in, 403 if you try to modify another user.
-Comments:
-Any fields which are specified in the request body will be set to the supplied values.  Fields which are omitted will be unchanged.
-
-### Reset user password ###
-Endpoint: /user?reset=*emailAddress*
-Method: PUT
-Request content-type: n/a
-Request body: none
-Response body: none
-Status: 204 on success, 404 if *emailAddress* is not found.
-Comments:
-A new random password will be generated and emailed to the user.
-
-
-### Ask to resend confirmation email ###
-Endpoint: /user?resend=*emailAddress*
-Method: PUT
-Request content-type: n/a
-Request body: none
-Response body: none
-Status: 204 on success, 404 if *emailAddress* is not found, 410 if *emailAddress* has already been confirmed.
-Comments:
-The confirmation email will be resent to the given email.
-
-
-## 2. Login ##
-
-### Log in to Tradamus ###
-Endpoint: /login
-Method: POST
-Request content-type: application/json
-Request body: { "mail" : "*emailAddress*", "password" : "*password*" }
-Response location: /user/*userID*
-Response body: none
-Response cookies: JSESSIONID=*sessionID*; Path=/Tradamus/; HttpOnly
-Status:  204 on success, 401 on invalid login.
-
-### Log out of Tradamus ###
-Endpoint: /login
-Method: POST
-Request content-type: n/a
-Request body: must be empty
-Response body: none
-Response cookies: JSESSIONID=*sessionID*; Path=/Tradamus/; HttpOnly
-Status:  204 on success.
-
-### Check login status ###
-Endpoint: /login
-Method: GET
-Request body: none
-Response content-type: application/json
-Response body: { "id":*userID*, "mail":"*emailAddress*","name":"*fullName*","disabled":false,"creation":*creationTime*,"lastLogin":*lastLoginTime* }
-Status: 200 if JSESSIONID is valid, 401 if it's not.
-
-## 3. Editions ##
+Draft 2015-05-27
+
+## 1. Editions ##

 Editions are created by POSTing JSON data to the /editions endpoint.  The list of editions can be retrieved by a GET request to the /editions endpoint.

@@ -256,7 +148,7 @@
 Deletes the single edition identified by *edID*.  Associated witnesses, transcriptions, pages, manifests, canvasses, images, outlines, parallels, and annotations will also be deleted.

-## 4. Witnesses ##
+## 2. Witnesses ##

 Witnesses are created by posting JSON, JSON-LD or XML data to an edition's `witnesses` endpoint.  The list of witnesses can be retrieved by a GET request to the edition's `witnesses` endpoint.

@@ -394,7 +286,7 @@
 Convenience function which aggregates the annotations from all canvasses and pages associated with the witness.

-## 5. Transcriptions ##
+## 3. 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.

@@ -445,7 +337,7 @@
 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.  Specify `"user":0` to set permissions for the "public sharing" user.  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 ##
+## 4. Pages ##

 ### Get page details ###
 Endpoint:  /page/*pageID*
@@ -518,7 +410,7 @@
 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 ##
+## 5. 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.

@@ -564,7 +456,7 @@
 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.  Specify `"user":0` to set permissions for the "public sharing" user.  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 ##
+## 6. Canvasses ##

 ### Get canvas details ###
 Endpoint:  /canvas/*canvID*
@@ -644,7 +536,7 @@
 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 ##
+## 7. Annotations ##

 ### Get annotation details ###
 Endpoint:  /annotation/*annID*
@@ -682,7 +574,7 @@
 Deletes the single annotation identified by *annID*.

-## 10. Outlines ##
+## 8. Outlines ##

 ### Get outline details ###
 Endpoint: /outline/*outlID*
@@ -718,7 +610,7 @@
 Sets the `approvedBy` field of the outline's decisions to the ID of the current user.  If the request body contains an array of annotation IDs, only those annotations will be marked as approved.  If the request body is absent, all the outline's decisions will be approved.

-## 11. Collation ##
+## 9. Collation ##

 Invokes the CollateX engine to generate a comparison of the specified witnesses.  CollateX is invoked with the Needleman-Wunsch algorithm.  The details of the collation can be controlled using the parameters described here:

@@ -801,76 +693,3 @@
 ]
 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.
-
-
-## 12. 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.
-
-
-## 13. 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`, `editions`, `images`, `manifests`, `outlines`, `pages`, `transcriptions`, `users`, or `witnesses`.  The optional `id` parameter identifies the particular entity of that type.
-limit=*limit* to limit the number of records returned
-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
-
-
-## 14. 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.

Edition API modified by Eric Smith

Eric Smith — Thu, 23 Apr 2015 22:16:57 -0000

--- v14
+++ v15
@@ -1,4 +1,4 @@
-Draft 2015-04-07
+Draft 2015-04-23

 ## 1. Users ##

@@ -724,7 +724,7 @@

 parameter         | value      | effect
 ----------------- | ---------- | -------
-comparison        | text       | Witnesses are compared using just their text content.
+comparison        | plain      | Witnesses are compared using just their text content.
 comparison        | morph      | Witnesses are compared based on their morphological content, using analysis performed by the Perseus morphology engine.
 comparison        | orth       | Witnesses are compared in an orthographically-aware manner, taking into account common spelling irregularities.  The `dict` parameter can be specified, to indicate the spelling dictionary to be used.
 dict              | lat        | Specifies a spelling dictionary to be used for `orth` comparison.  May be specified multiple times to use multiple spelling dictionaries.
@@ -743,7 +743,7 @@
 Method:  POST
 Request body:  none
 Request parameters:
-`comparison=text|morph|orth` (default `text`)
+`comparison=plain|morph|orth` (default `plain`)
 `dict=`*dictionary* (default `lat`; may be specified multiple times)
 `ignoreCase=true|false` (default `false`)
 `ignoreLineBreaks=true|hyphens|false` (default `false`)

Edition API modified by Eric Smith

Eric Smith — Wed, 08 Apr 2015 01:50:39 -0000

--- v13
+++ v14
@@ -1,4 +1,4 @@
-Draft 2015-03-26
+Draft 2015-04-07

 ## 1. Users ##

@@ -570,10 +570,10 @@
 Endpoint:  /canvas/*canvID*
 Method:  GET
 Request body:  none
-Response body:  {"id":12,"title":"R2v.jpg","page":12,"manifest":3}
+Response body:  {"id":1001,"index":1,"title":"R3.jpg","width":1472,"height":1000,"images":\[{"id":2,"index":0,"uri":"http://localhost:8080/T-PEN/imageResize?folioNum=12841944&height=1000&user=ericsmith@slu.edu","format":"JPEG","width":1472,"height":2000,"canvas":1001}],"manifest":1,"page":1001}
 Status:  200 on success, 404 if *canvID* does not exist.
 Comments:
-The "index" field contains the canvas' index within the manifest as a whole.
+The "index" field contains the canvas' index within the manifest as a whole.  For convenience, the response body also contains the canvas' "images" array.

 ### Set canvas details ###
 Endpoint:  /canvas/*canvID*
@@ -613,6 +613,16 @@
 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.
+
+### Set canvas images ###
+Endpoint:  /canvas/*canvID*/images
+Method: PUT
+Request body:  \[{"id":2,"index":0,"uri":"http://localhost:8080/TPEN/imageResize?folioNum=12841944&height=1000&user=ericsmith@slu.edu","format":"JPEG","width":1472,"height":2000,"canvas":1001},…]
+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' images.  If the `merge` parameter is `false`, the existing images will be completely replaced; if it is `true` or omitted, only images mentioned in the request body will be affected.

 ### Get canvas lines ###
 Endpoint:  /canvas/*canvID*/lines

Edition API modified by Eric Smith

Eric Smith — Thu, 26 Mar 2015 20:11:05 -0000

--- v12
+++ v13
@@ -1,4 +1,4 @@
-Draft 2015-02-20
+Draft 2015-03-26

 ## 1. Users ##

@@ -244,7 +244,7 @@
 Response body:  none
 Status: 204 on success, 404 if *edID* 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 edition.  If the `merge` parameter is `false`, the contents of the array will completely replace the edition's existing permissions; if it is `true` or omitted, only permissions mentioned in the request body will be affected.
+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 edition.  Specify `"user":0` to set permissions for the "public sharing" user.  If the `merge` parameter is `false`, the contents of the array will completely replace the edition's existing permissions; if it is `true` or omitted, only permissions mentioned in the request body will be affected.

 ### Delete an edition ###
 Endpoint:  /edition/*edID*
@@ -442,7 +442,7 @@
 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.
+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.  Specify `"user":0` to set permissions for the "public sharing" user.  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 ##
@@ -561,7 +561,7 @@
 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.
+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.  Specify `"user":0` to set permissions for the "public sharing" user.  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 ##

Edition API modified by Eric Smith

Eric Smith — Fri, 20 Feb 2015 17:55:29 -0000

--- v11
+++ v12
@@ -1,4 +1,4 @@
-Draft 2015-01-07
+Draft 2015-02-20

 ## 1. Users ##

@@ -670,6 +670,7 @@
 Status:  204 on success.
 Comments:
 Deletes the single annotation identified by *annID*.
+

 ## 10. Outlines ##

@@ -808,6 +809,7 @@
 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`, `editions`, `images`, `manifests`, `outlines`, `pages`, `transcriptions`, `users`, or `witnesses`.  The optional `id` parameter identifies the particular entity of that type.
+limit=*limit* to limit the number of records returned
 Request body:  none
 Response body:  An array of activity records:
 \[

Edition API modified by Eric Smith

Eric Smith — Wed, 07 Jan 2015 21:54:46 -0000

--- v10
+++ v11
@@ -1,4 +1,4 @@
-Draft 2014-12-05
+Draft 2015-01-07

 ## 1. Users ##

@@ -278,6 +278,16 @@
 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.
+
+### Link JSON-LD witness from T-PEN ###
+Endpoint: /edition/*edID*/witnesses
+Method: POST
+Parameters: `src` URL of JSON-LD source (i.e. T-PEN project)
+Request content-type: application/ld+json
+Request body: none
+Status: 201 on success, 404 if *edID* does not exist, or error codes from T-PEN
+Comments:
+This differs from importing a JSON-LD witness because the call creates a persistent link to T-PEN which is checked for updates every time the user logs in.

 ### Import XML witness ###
 Endpoint: /edition/*edID*/witnesses