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

See also

External links

OneGeology

Vocabulary web service — version 1.0

Contents

Usage