Data Enrichment Service API

URI Scheme

Group	URI Pattern	HTTP Method	Method Details
Enriching Content
Submit some text to latest version of DES	/enriched-text	POST	Returns a page with enriched content.
Submit some text to a version of DES	/{versionNumber}/enriched-text	POST	Returns a page with enriched content as the DES was at version 'versionNumber'.
Submit a file to latest version of DES	/enriched	POST	Returns a page with enriched content.
Submit a file to a version of DES	/{versionNumber}/enriched	POST	Returns a page with enriched content as the DES was at version 'versionNumber'.

Submission Parameters

The following is the list of parameters to use for submission:

URI(s)	Parameter Name	Purpose	Notes
enriched-text	text	Contains the content being submitted.
enriched	file	The file being submitted.
enriched enriched-text	fileEncoding	Defines the encoding of the content being submitted. Note that for POSTing text it is highly recommended to use the default of UTF-8.
enriched enriched-text	format	Defines the requested return format.	See the section on Available Formats below.

Formats Acceptable for Submission

The DES can accept files with a MIME type of text/plain. These are limited to 10000 bytes at present.

Available Formats for Enriched Content

The system can provide a response in either RDF/XML, RDFa, JSON, XML or, under certain conditions HTML. This can be controlled either through a 'format' parameter or through content negotiation. The list is given in the table below:

Required Format	Value for 'format'	Notes
RDF/XML	rdfxml
RDFa	rdfa
JSON	json	If you want a JSONP callback to be returned add a parameter callback={methodName}, where methodName is the name of the method to be invoked.
XML	xml

Content Negotiation

The system utilises content negotiation for enrichment. The available formats are RDF/XML, RDFa, JSON and XML, with the default being XML.

Required Format	Accept Header MIME type	Notes
RDF/XML	application/rdf+xml
RDFa	application/xhtml+xml	Currently RDFa is served as text/html due to limitations of Internet Explorer.
JSON	application/json
XML	application/xml

Versioning

If you make a call to the DES the latest version of the service will be used by default. However, if you wish to hardcode your calls to a specific version of the DES then you can use versioned URIs of the form '/1.0/enriched-text'. This will ensure that the content you receive stays the same even though the latest version of the DES may be returning different results.

If you inadvertenly try to call the service with a version number that does not actually exist then the system will attempt to calculate the most logical version to give back. For instance if you ask for version '1.1' and it does not exist you will get back version '1.0'.

Using Curl to Access the Service

To POST some text to the DES the following command line can be used:

curl -d "text=Is John Smith here?" http://openup.tso.co.uk/des/enriched-text

It is important to use the -d switch (rather than -F) as the data needs to be in application/x-www-form-urlencoded encoding when submitting text.

The text parameter should contain the text to be enriched. By default the service will return XML.

To POST a file to the DES the following command line can be used:

curl -F "file=@test-document-1.txt" http://openup.tso.co.uk/des/enriched

If you want to control the information about the encoding of your file include a fileEncoding parameter, e.g. -F "fileEncoding=UTF-8"