This document describes version 1.0 of the BGS Vocabulary Service.
Usage
The vocabulary service has been implemented as a using the framework.
Information is exposed through a series of , where each resource implements the standard interface and is identified by a . Each resource provides representations of information for a number of supported .
The vocabulary service supportsto 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, 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 | |
| Search vocabularies | /vocabularies?q={query}&start={start}&size={size} | GET | text/xml application/json | |
| Fetch a vocabulary | /vocabularies/{vocabularyId} | GET | text/xml application/json application/vnd.ms-excel | |
| List vocabulary terms | /vocabularies/{vocabularyId}/terms | GET | text/xml application/json application/vnd.ms-excel | |
| Fetch a vocabulary term | /vocabularies/{vocabularyId}/terms/{termId} | GET | text/xml application/json |
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
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 usingformat, and NULL values are indicated using thenil 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Μύ΄Η°ωΜύ.
MEDIA TYPE: application/json
EXTENSION: 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 theexample tableis:
CODE: String DESCRIPTION: String TRANSLATION: String STATUS: String DATE_ENTERED: Date DATE_UPDATED: Date
MEDIA TYPE: application/vnd.ms-excel
EXTENSION: xls
Excel worksheetrepresentations return a document containing a set of vocabulary terms in tabular form.
Status codes
The vocabulary service returns defined by the .
The most relevant status codes are:
- : A 200 response code is returned if a request is successful.
- : 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.
- : 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.
- : 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:
- JavaScript:
- Ruby:
- .NET:
You may also be interested in:
Technologies
Applications, software and online services created by the BGS and our collaborators.