Vocabulary web service — version 1.0

This document describes version 1.0 of the BGS Vocabulary Service.

Contents

Usage

The vocabulary service has been implemented as a RESTful web service using the Restlet framework.

Information is exposed through a series of resources, where each resource implements the standard HTTP interface and is identified by a URL. Each resource provides representations of information for a number of supported media types.

The vocabulary service supports content negotiation to provide the most appropriate representation for a particular client. For example to request a JSON representation of a resource, a client should use the following HTTP header in its request:

Accept: application/json

Not all clients will be able to add or modify HTTP headers, therefore the vocabulary service supports other ways to specify the required representation format. Each media type has been mapped to a file extension. Each resource supports a media parameter in the query string which may be used to tunnel the required media type. A JSON representation would be returned by the following:

/vocabularies?media=json

Additionally like in Ruby on Rails, the file extension may be appended to the URL:

/vocabularies.json

Resources

All resources are relative to http://webservices.bgs.ac.uk/data/services/vocabulary/1.0

Operation URL Method Media Types Examples
List vocabularies /vocabularies GET text/xml
application/json
/vocabularies
Search vocabularies /vocabularies?q={query}&start={start}&size={size} GET text/xml
application/json
/vocabularies?q=borehole

/vocabularies?q=borehole&start=5&size=10
Fetch a vocabulary /vocabularies/{vocabularyId} GET text/xml
application/json
application/vnd.ms-excel
/vocabularies/DIC_GEOCHRON_RANK

/vocabularies/DIC_GEOCHRON_RANK.xls
List vocabulary terms /vocabularies/{vocabularyId}/terms GET text/xml
application/json
application/vnd.ms-excel
/vocabularies/DIC_GEOCHRON_RANK/terms

/vocabularies/DIC_DTA_REF_MATERIAL/terms?media=json
Fetch a vocabulary term /vocabularies/{vocabularyId}/terms/{termId} GET text/xml
application/json
/vocabularies/DIC_GEOCHRON_RANK/terms/SUB-ERA

/vocabularies/DIC_GEOCHRON_RANK/terms/SUB-ERA.xml

Supported media types

Media Type Name Extension
text/xml Extensible Markup Language xml
application/json JavaScript Object Notation json
application/vnd.ms-excel Excel Worksheet xls

Extensible Markup Language

Media Type
text/xml
Extension
xml

XML representations use the following structure:

<vocabularies>
  <vocabulary xlink:href="{vocabularyRef}">
    <id>{vocabularyId}</id>
    <description>{description}</description>
    <terms xlink:href="{termsRef}">
      <term xlink:href="{termRef}" />
    </terms>
  </vocabulary>
</vocabularies>

The structure of term elements is dependant upon the structure of the table they originate from. Many BGS vocabularies use the following database structure:

CREATE TABLE VOCABULARY_NAME
(
  CODE VARCHAR2(10) PRIMARY KEY,
  DESCRIPTION VARCHAR2(200),
  TRANSLATION  VARCHAR2(50),
  STATUS CHAR(1),
  DATE_ENTERED DATE,
  DATE_UPDATED DATE
);

Terms from this vocabulary would be represented as:

<term xlink:href="{termRef}>
  <CODE>{CODE}</CODE>
  <DESCRIPTION>{DESCRIPTION}</DESCRIPTION>
  <TRANSLATION>{TRANSLATION}</TRANSLATION>
  <STATUS>{STATUS}</STATUS>
  <DATE_ENTERED>{DATE_ENTERED}</DATE_ENTERED>
  <DATE_UPDATED>{DATE_UPDATED}</DATE_UPDATED>
</term>

Date values are encoded using ISO 8601 format, and NULL values are indicated using the XML Schema nil attribute:

<DATE_ENTERED>1993-12-16</DATE_ENTERED>
<DATE_UPDATED xsi:nil="true"/>

Future versions of the vocabulary server may use standard schemas such as RDF or Atom.

JavaScript Object Notation

Media Type
application/json
Extension
json

JSON representations return Vocabulary, Term or Array objects. The type of object returned depends on the resource, for example, /vocabularies returns an array of Vocabulary objects.

Vocabulary

id
String
description
String
terms
Term Array

Term

The properties of a term object depend upon the structure of the table they originate from. The JSON term object that would result from the example table is:

CODE
String
DESCRIPTION
String
TRANSLATION
String
STATUS
String
DATE_ENTERED
Date
DATE_UPDATED
Date

Excel worksheet

Media Type
application/vnd.ms-excel
Extension
xls

Excel worksheet representations return a document containing a set of vocabulary terms in tabular form.

Status Codes

The vocabulary service returns status codes defined by the HTTP 1.1 specification.

The most relevant status codes are:

200 OK
A 200 response code is returned if a request is successful.
404 Not Found
A 404 response code is returned if a requested resource could not be found. For example, if the requested vocabulary does not exist, or if the requested term does not exist within a vocabulary.
415 Unsupported Media Type
A 415 response code is returned if an inappropriate media type is requested. For example, requesting a application/vnd.ms-excel representation from the /vocabularies resource.
500 Internal Server Error
A 500 response code is returned if an unexpected error occurs on the server.

Clients

Clients can be written with any tool that supports the HTTP protocol. Some examples include:

Java
Restlet
HttpClient
HttpURLConnection
JavaScript
XMLHttpRequest
dojo.data
Ruby
ActiveResource
.NET
System.Web.HTTPWebRequest