Use cases | Beckett | Darwin | REST service

REST service

This is the REST service of CollateX. To call it, you can post witness data as specified below and get the collation result back in a number of formats.

Input

The service is callable via HTTP POST requests. It expects witness data formatted in JavaScript Object Notation (JSON) as the request body; accordingly the content type of the request must be set to application/json.

A typical request’s content might look as follows:

Content-Type: application/json;charset=UTF-8
	
{
	"witnesses" : [
	        {"id" : "A", "content" : "A black cat in a black basket" }, 
	        {"id" : "B", "content" : "A black cat in a black basket" },
	        {"id" : "C", "content" : "A striped cat in a black basket" },
	        {"id" : "D", "content" : "A striped cat in a white basket" }
	        ]
}

The root object in the body must contain a property witnesses, which contains a list of witness objects in turn. Each witness object has to contain a unique identifier in the property id. Besides the object can either contain the textual content of the witness as a string property named content (as shown above). The other option is a pre-tokenized witness, that is comprised of list of tokens notated as follows:

{
        "witnesses" : [
                {"id" : "A", "tokens" : [
                        { "t" : "A" },
                        { "t" : "black" },
                        { "t" : "cat" }
                        ]}, 
                {"id" : "B", "tokens" : [
                        { "t" : "A" },
                        { "t" : "white" },
                        { "t" : "kitten.", "n" : "cat" }
                        ]}
                ]
}

Each token object has to contain a property t, which contains the token itself. Optionally a “normalized” version of the token can be provided in the property n. It can be any kind of alternate version, the collator should use in precendence over the original token while matching witnesses. Apart from these two known properties and two reserved ones (position and sigle), token objects can contain further properties, which will not be interpreted by the collator but just passed through in the output.

Output

The output format of the collator, represented in the response to the HTTP POST request, can be chosen via the Accept HTTP header. The following MIME types aka. output formats are supported:

application/json:: the alignment of the witnesses, represented in JSON,
application/xml:: the collation result as a critical apparatus, encoded in TEI P5 parallel segmentation mode,
application/graphml+xml:: the variant graph, represented in GraphML format, or
per default:: a HTML representation of the alignment in tabular form.

Example: Alignment table in JSON

The indentation is added for readability and not included in the output. Gaps in the table are represented by null.

{"alignment":[        
	{"witness":"A","tokens":[                
		{"t":"A","n":"a"},                
		{"t":"nice","n":"nice"},                
		{"t":"black","n":"black"},                
		{"t":"cat.","n":"cat"},                
		null,                
		null,                
		null]},        
	{"witness":"B","tokens":[                
		{"t":"A","n":"a"},                
		{"t":"white","n":"white"},                
		null,                
		{"t":"kitten","n":"cat"},                
		{"t":"in","n":"in"},
                {"t":"a","n":"a"},
                {"t":"basket.","n":"basket"}]}
        ]
}

Example: Critical apparatus in TEI P5


A 
        nice black
        white
     
        cat.
        kitten
     
        
        in a basket.
    
]]>

Example: Variant graph in GraphML format

For the example witnesses from the Input section above, the output in GraphML format will look as follows. The 'identical' key, not used here, is set for those nodes that are transposed duplicates of other nodes.