Recent changes to CollationAPI

CollationAPI modified by Domhnall101

Domhnall101 — Tue, 06 Oct 2015 19:30:30 -0000

--- v4
+++ v5
@@ -1,5 +1,6 @@
 Draft 2015-06-16

+###Collation API
 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

Collation API modified by Eric Smith

Eric Smith — Tue, 16 Jun 2015 15:18:46 -0000

--- v3
+++ v4
@@ -1,4 +1,4 @@
-Draft 2015-06-15
+Draft 2015-06-16

 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:

@@ -46,7 +46,7 @@
    ],
    …
 ]
-Status:  200 on success, 201 if `deferred=true`, 404 if *edID* does not exist.
+Status:  200 on success if `deferred=false` or 303 if `deferred=true`, 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.  If `deferred=true` is supplied on the parameter list, the response body will be empty, but the location header will return the URI where the results of the collation will be available.

 ### Sub-collation ###
@@ -82,5 +82,5 @@
    ],
    …
 ]
-Status:  200 on success, 201 if `deferred=true`, 400 if the text ranges are not consistent (e.g. a range has a negative length, or refers to pages from two separate witnesses).
+Status:  200 on success if `deferred=false` or 303 if `deferred=true`, 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.  If `deferred=true` is supplied on the parameter list, the response body will be empty, but the location header will return the URI where the results of the collation will be available.

Collation API modified by Eric Smith

Eric Smith — Mon, 15 Jun 2015 20:04:41 -0000

--- v2
+++ v3
@@ -1,4 +1,4 @@
-Draft 2015-06-04
+Draft 2015-06-15

 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:

@@ -29,8 +29,10 @@
 `ignoreLineBreaks=true|hyphens|false` (default `false`)
 `ignorePunctuation=true|false` (default `false`)
 `useTEITags=true|false` (default `false`)
+`deferred=true|false` (default `false`)
 Response content-type:  application/json
-Response body:  an array of arrays of mote annotations:
+Response location: if `deferred=true`, `/deliverable/`*delID*
+Response body:  an array of arrays of mote annotations (empty if `deferred=true`):
 \[
    \[
       {"content":"Lectio 1, Prologus","endOffset":18,"target":"#2","endPage":2000,"startPage":2000,"startOffset":0,"type":"tr-mote"},
@@ -44,9 +46,8 @@
    ],
    …
 ]
-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.
-
+Status:  200 on success, 201 if `deferred=true`, 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.  If `deferred=true` is supplied on the parameter list, the response body will be empty, but the location header will return the URI where the results of the collation will be available.

 ### Sub-collation ###
 Endpoint:  /collation
@@ -64,8 +65,10 @@
 `ignoreLineBreaks=true|hyphens|false` (default `false`)
 `ignorePunctuation=true|false` (default `false`)
 `useTEITags=true|false` (default `false`)
+`deferred=true|false` (default `false`)
 Response content-type:  application/json
-Response body:  an array of arrays of mote annotations:
+Response location: if `deferred=true`, `/deliverable/`*delID*
+Response body:  an array of arrays of mote annotations (empty if `deferred=true`):
 \[
    \[
       {"content":"Lectio 1, Prologus","endOffset":18,"target":"#2","endPage":2000,"startPage":2000,"startOffset":0,"type":"tr-mote"},
@@ -79,5 +82,5 @@
    ],
    …
 ]
-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.
+Status:  200 on success, 201 if `deferred=true`, 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.  If `deferred=true` is supplied on the parameter list, the response body will be empty, but the location header will return the URI where the results of the collation will be available.

Collation API modified by Eric Smith

Eric Smith — Thu, 04 Jun 2015 17:28:22 -0000

--- v1
+++ v2
@@ -1,3 +1,5 @@
+Draft 2015-06-04
+
 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

Collation API modified by Eric Smith

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

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) 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.