This document describes version 1.0 of the BGS Vocabulary Service.
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, so 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 |
| Fetch a vocabulary | /vocabularies/{vocabularyId} | GET | text/xml application/json application/vnd.ms-excel | /vocabularies/DIC_GEOCHRON_RANK |
| List vocabulary terms | /vocabularies/{vocabularyId}/terms | GET | text/xml application/json application/vnd.ms-excel | /vocabularies/DIC_GEOCHRON_RANK/terms |
| Fetch a vocabulary term | /vocabularies/{vocabularyId}/terms/{termId} | GET | text/xml application/json | /vocabularies/DIC_GEOCHRON_RANK/terms/SUB-ERA |
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 |
- Media Type: text/xml
- Extension: xml
XML representations use the following structure:
<vocabularies> <vocabulary xlink:target=”_blank” href=”{vocabularyRef}”> <id>{vocabularyId}</id> <description>{description}</description> <terms xlink:target=”_blank” href=”{termsRef}”> <term xlink:target=”_blank” 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:target=”_blank” 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.
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.
ID: String DESCRIPTION: String TERMS: Term Array
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
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
You may also be interested in:
Technologies
Applications, software and online services created by the BGS and our collaborators.