Data Enrichment Service API

URI Scheme

 

GroupURI PatternHTTP MethodMethod Details
Enriching Content
Submit some text to latest version of DES/enriched-textPOSTReturns a page with enriched content.
Submit some text to a version of DES/{versionNumber}/enriched-textPOSTReturns a page with enriched content as the DES was at version 'versionNumber'.
Submit a file to latest version of DES/enrichedPOSTReturns a page with enriched content.
Submit a file to a version of DES/{versionNumber}/enrichedPOSTReturns 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 NamePurposeNotes
enriched-texttextContains the content being submitted.
enrichedfileThe file being submitted.
enriched

enriched-text
fileEncodingDefines 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
formatDefines 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 FormatValue for 'format'Notes
RDF/XMLrdfxml
RDFardfa
JSONjsonIf you want a JSONP callback to be returned add a parameter callback={methodName}, where methodName is the name of the method to be invoked.
XMLxml

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 FormatAccept Header MIME typeNotes
RDF/XMLapplication/rdf+xml
RDFaapplication/xhtml+xmlCurrently RDFa is served as text/html due to limitations of Internet Explorer.
JSONapplication/json
XMLapplication/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"