Skip to content
This repository has been archived by the owner on Sep 17, 2024. It is now read-only.

GatewayAPIs

Jump to bottom
Dave Vieglais edited this page Aug 26, 2011 · 15 revisions

REST API Exposed by the Gateway

Last Modified: 2011-08-25
Version: 1.2.0
Author: Dave Vieglais

This document describes an API that provides a common set of methods for accessing content held in a collection composed of a set of records constructed from a list of fields.

Version History

Version Description
1.0 First iteration of API descriptions
1.0.1 Added error descriptions for methods
1.1.0 Changed definition of FieldList to include the same information as FieldInfo; Added optional key for "label" and a boolean "multivalued" entry to field description.
1.2.0 Added filter parameter to getFieldValues and removed the start parameter. Added a fieldHistogram operation which returns a set of histogram bins.
1.2.1 Added numRecords to getFieldValues response. Renamed fieldHistogram to getFieldHistogram and adjusted URL to .../fields/{name}/histogram

Service Interface URLs

URL HTTP Method Name Parameters Return
{base}/ GET getSummary   Collection metadata CollectionInfo
{base}/fields GET getFields   List of Fields FieldList
{base}/fields/{name} GET getField name (as URL path) Field metadata FieldInfo
{base}/fields/{name}/values GET getFieldValues name (as URL path), filter, count Field distinct values FieldValues
{base}/fields/{name}/histogram GET getFieldHistogram_ name (as URL path), filter, bins Histogram of values matching filter.
{base}/records GET getRecords start, count [,orderby] [,order ] [,fields] [,filter] List of Records RecordList
{base}/record/{id} GET getRecord id (as URL path part) Document identified by id

Methods

getSummary

Return a summary of the collection that is accessible at this location.

URL: {base}/

Parameters

None

Return

rtype: JSON serialized CollectionInfo
returns: Summary information for the collection

Errors

Status Name Description
405 Method Not Allowed The HTTP method used to access the resource is not permitted (e.g. using POST instead of GET)
406 Not Acceptable The service is not able to respond with the requested content type as indicated in the request accept headers.

Example

curl "http://service/base/"

{'url': 'http://service/base/',
 'numRecords': 635881,
 'lastModified': '2010-05-11T22:12:34Z',
 'currentTime': '2011-06-14T07:39:34Z'}

getFields()

Returns a list of names of fields supported by the collection.

URL: {base}/fields

Parameters

None

Return

rtype: JSON serialized FieldList
returns: A list of fields available in the collection

Errors

Status Name Description
405 Method Not Allowed The HTTP method used to access the resource is not permitted (e.g. using POST instead of GET)
406 Not Acceptable The service is not able to respond with the requested content type as indicated in the request accept headers.

Example

curl "http://service/base/fields"

{ 'id' : {
     'type': 'STRING',
     'distinct': 650123,
     'stored': true,
     'multivalued': false,
     'label': 'ID' }
  'text' : {
     'type': 'TEXT',
     'distinct': 34823,
     'stored': true,
     'multivalued': false,
     'label': 'Full Text' },
  'keywords' : {
     'type': 'STRING',
     'distinct': 34348,
     'stored': true,
     'multivalued': true,
     'label': 'Keywords' },
  'created' : {
    'type': 'DATE',
    'distinct': 13,
    'stored': true,
    'multivalued': false,
    'label': 'Created' },
  ... }

getField()

Returns basic metadata about a field that can be used for assisting with dynamically generated user interfaces.

URL: {base}/fields/{name}

Parameters

name: The name of the field being examined. This value is expressed as part of the URL path.

Return

rtype: JSON serialized FieldInfo
returns: Metadata about a particular field

Errors

Status Name Description
405 Method Not Allowed The HTTP method used to access the resource is not permitted (e.g. using POST instead of GET)
406 Not Acceptable The service is not able to respond with the requested content type as indicated in the request accept headers.
404 Not Found The field name as indicated in the URL path does not exist.

Example

curl "http://service/base/fields/created"

{'created' : {
   'type': 'DATE',
   'distinct': 13,
   'stored': true,
   'multivalued': false,
   'label': 'Created' }
   }

getFieldValues()

Retrieves a list of distinct values present in the field, and the number of occurrences of each value. The values provided are adjusted according to the current result set which is specified by the filter parameter.

URL: {base}/fields/{name}/values[?filter={filter}][&count={count}]

Parameters

name: The name of the field being examined. This value is expressed as part of the URL path.
filter: A query string in a syntax supported by the target collection that will be used to restrict the size of the results. Default filter is ":" which matches everything.
count: The total number of values returned in the request. -1 returns all. Default = 1000.

Return

rtype: JSON serialized FieldValues
returns: A list of distinct values and their occurrences as reported by the index.

Errors

Status Name Description
405 Method Not Allowed The HTTP method used to access the resource is not permitted (e.g. using POST instead of GET)
406 Not Acceptable The service is not able to respond with the requested content type as indicated in the request accept headers.
404 Not Found The field name as indicated in the URL path does not exist.

Example

curl "http://service/base/fields/created/values"

{ "numRecords": 635881,
  "values": [ ['2009-03-11T02:18:14Z',161906],
            ['2009-03-11T01:59:26Z',121375],
            ['2009-03-11T01:10:49Z',76274],
            ['2009-03-11T02:01:09Z',70220],
            ['2009-03-10T01:34:00Z',52013],
            ['2009-03-10T14:46:03Z',51956],
            ['2009-03-10T01:37:02Z',36627],
            ['2009-03-10T01:32:17Z',34379],
            ['2009-04-01T16:06:19Z',15777],
            ['2009-04-01T19:50:52Z',4745],
            ['2009-03-10T15:31:55Z',3555],
            ['2009-04-01T20:11:25Z',3537],
            ['2009-03-10T01:33:13Z',3517] ] }

getFieldHistogram()

Retrieves a histogram of values for a field from the values present in a subset as specified by a filter.

URL: {base}/fields/{name}/histogram[?filter={filter}] [&bins={bins}]

Parameters

filter: A query string in a syntax supported by the target collection that will be used to restrict the size of the results. Default filter is ":" which matches everything.
bins: The number of bins that will appear in the results. Default is 10.

Example

TODO.

getRecords()

Retrieves a page of records from a subset of the collection as identified by a filter.

URL: {base}/records[?start={start}] [&count={count}] [&orderby={orderby}] [&order={order}] [&fields={fields}] [&filter={filter}]

Parameters

start: The zero based index of the first record to retrieve. Default is 0.
count: The maximum number of records to retrieve (page size). Default is 1000.
orderby: The name of the field that will be used to order the results. Default is collection specific.
order: Either "ASC" or "DESC" indicating ascending or descending sort order respectively. The default value is "ASC".
fields: A comma delimited list of field names that are to appear in the results for each record. Default is to return all fields. The default is "*" which returns all fields.
filter: A query string in a syntax supported by the target collection that will be used to restrict the size of the results. Default filter is ":" which matches everything.

Return

rtype: JSON serialized RecordList
returns: Summary information for the collection

Errors

Status Name Description
405 Method Not Allowed The HTTP method used to access the resource is not permitted (e.g. using POST instead of GET)
406 Not Acceptable The service is not able to respond with the requested content type as indicated in the request accept headers.
400 Bad Request Parameters specified in the request are invalid. The error description and optionally the debug field should contain information to assist the caller in determining what caused the error.

Example

curl "http://service/base/records?start=0 \
 &count=5\
 &orderby=lat\
 &order=ASC\
 &fields=id,created,lat,lng\
 &filter=collCode_s:FISH"

{'numFound':161906,
 'start:0,
 'docs':[
  {
   "created":"2009-03-11T02:18:14Z",
   "id":["MCZ.FISH.41611."],
   "lng":[166.73],
   "lat":[-77.88]},
  {
   "created":"2009-03-11T02:18:14Z",
   "id":["MCZ.FISH.42517."],
   "lng":[166.73],
   "lat":[-77.88]},
  {
   "created":"2009-03-11T02:18:14Z",
   "id":["MCZ.FISH.42519."],
   "lng":[166.73],
   "lat":[-77.88]},
  {
   "created":"2009-03-11T02:18:14Z",
   "id":["MCZ.FISH.42520."],
   "lng":[166.73],
   "lat":[-77.88]},
  {
   "created":"2009-03-11T02:18:14Z",
   "id":["MCZ.FISH.42518."],
   "lng":[166.65],
   "lat":[-77.85]}
   ]}

getRecord()

Retrieves a single record from the collection.

URL: {base}/record/{id}

Parameters

id: The unique identifier for the record. The identifier is expressed as part of the URL path, and so MUST be properly URL path encoded as per RFC3986.

Return

rtype: Octet stream
return: The document identified by {id}. The document should be a literal representation of the content held in the collection and identified by {id}.

Errors

Status Name Description
405 Method Not Allowed The HTTP method used to access the resource is not permitted (e.g. using POST instead of GET)
406 Not Acceptable The service is not able to respond with the requested content type as indicated in the request accept headers.
404 Not Found The field name as indicated in the URL path does not exist.

Error Handling

Errors that prevent the successful completion of any of the API methods should be handled in a way that informs the client of the likely problem.

An error condition is communicated by a HTTP response status code in the 400 or higher range. A list of error codes relevant to this API are listed below. Refer to the HTTP specification for a complete reference of HTTP status codes.

HTTP error codes of relevance to the DataONE cicore are repeated here for convenience. Refer to the HTTP specification for a complete reference.

Code Meaning Description
400 Bad Request The request REST operation is invalid, serialization is erroneous, mime type is not supported, or resource is not supported.
401 Unauthorized Authentication failure. Credentials are required or were invalid.
403 Forbidden The current user does not have the right to perform the requested action.
404 Not Found The requested resource does not exist.
405 Method not allowed The HTTP method used is not allowed on this resource. Response must include an Allow header indicating valid HTTP methods.
406 Not Acceptable The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request.
408 Request Timeout The client did not produce a request within the time that the server was prepared to wait.
409 Conflict The request could not be completed due to a conflict with the current state of the resource.
410 Gone The resource is known to be permanently deleted (as opposed to 404 which indicates uncertainty about the state of the object).
413 Request Entity Too Large The server is refusing to process a request because the request entity is larger than the server is willing or able to process.
415 Unsupported Media Type The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.
501 Not Implemented The server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource.

The response body of an error condition should include a JSON encoded Error structure, for example:

{'name': 'NotFound',
 'description': 'The requested resource is not available.'
 'debug': 'Optional information helpful for debugging can be included'}

Data Types

CollectionInfo

images/class_collectioninfo.png
url: The URL used to access the collection
numRecords: The total number of records available in the collection
lastModified: The time that the collection was last modified
currentTime: The time when this response was generated

FieldInfo

images/class_fieldinfo.png
field_name: The name of the field
type: The type of the field (e.g. STRING, DATE, TEXT, SFLOAT, INTEGER)
distinct: The number of distinct terms appearing in the field
stored: True if the field values are available for retrieval
multivalued: True if the field can contain multiple values
label: An optional human readable label for the field

FieldList

images/class_fieldlist.png

FieldList is a dictionary with keys being the name of the field and the value being a FieldInfo.

FieldValues

images/class_fieldvalues.png

FieldValues is a list of tuples, each tuple representing a value known to occur in the field and the number of records that value appears in.

RecordList

images/class_recordlist.png

A list of records returned from the search operation. The fields present in each Record is determined by the list of fields requested.

Error

image/class_error.png
Clone this wiki locally