Overview of Common Attributes

Transport Protocol

The API is based on the Hypertext Transfer Protocol, version 1.1 (RFC 2616).

Media Types

In the API, resource representations and request bodies are normally encoded in JSON, as specified in RFC4267. Each type of resource has its own media-type, which matches the pattern application/vnd.com.esha.data.xxxxx+json, where “xxxxx” represents the portion of the identifier unique to a particular representation format for each service.

Authentication

When making a request to the API, include your API key as query string parameter named apikey. You can apply for an API key here: http://developer.esha.com/apps/register.

Request Headers

In requests made to the API, several specific HTTP headers are used as described in the following table:

Header Supported Values Description of Use Required
Accept Comma-delimited list of media types or media type patterns. Indicates to the server what media type(s) this client is prepared to accept. Recommended, on requests that will produce a response message body.
Content-Length Length (in bytes) of the request message body. Describes the size of the message body. Yes, on requests that contain a message body.
Content-Type Media type describing the request message body. Describes the representation and syntax of the request message body. Yes, on requests that contain a message body.

Note that, since all interactions with the API is stateless, no Cookie header (or any other mechanism to provide a session identifier) is used.

Request Parameters

Since the URI space is controlled by the server, client programs MUST not make any assumptions about the meanings of request parameters not specifically described in the API.

Response Headers

In responses returned by the API, several specific HTTP headers are used as described in the following table:

Header Supported Values Description of Use Required
Content-Length Length (in bytes) of the response message body. Describes the size of the message body. Yes, on responses that contain a message body.
Content-Type Media type describing the response message body. Describes the representation and syntax of the response message body. Yes, on responses that contain a message body.

Standard HTTP Status Codes

The API will return standard HTTP response codes as described in the following table, under the conditions listed in the description:

HTTP Status Description
200 OK The request was successfully completed.
400 Bad Request The request could not be processed because it contains missing or invalid information (such as validation error on an input field, a missing required value, and so on).
403 Not Authorized
 You are not authorized to make calls to the API. You need to register for an account, http://developer.esha.com/member/register, and then apply for an API key, http://developer.esha.com/apps/register.
403 Developer Inactive Your account is inactive. Contact Esha Research for support.
403 Over Queries Per Second Limit You have issued too many queries per second. You can find your quota here: http://developer.esha.com/apps/register. Contact Esha Research to obtain a more liberal limit.
403 Over Rate Limit
 You have issued too many queries per day. You can find your quota here: http://developer.esha.com/apps/register. Contact Esha Research to obtain a more liberal limit.
403 Unknown Referer
 This may occur if you are tying keys to referring urls.
403 Service over QPS Limit Same as 403 Over Queries Per Second Limit above. You have issued too many queries per second. You can find your quota here: http://developer.esha.com/apps/register. Contact Esha Research to obtain a more liberal limit.
404 Not Found The request specified a URI of a resource that does not exist.
405 Method Not Allowed The HTTP verb specified in the request (DELETE, GET, HEAD, POST, PUT) is not supported for this request URI.
406 Not Acceptable The resource identified by this request is not capable of generating a representation corresponding to one of the media types in the Accept header of the request.
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.
501 Not Implemented The server does not (currently) support the functionality required to fulfill the request.
503 Service Unavailable The server is currently unable to handle the request due to temporary overloading or maintenance of the server.
504 Gateway Timeout
 The gateway has timed out. Try again later.

Error Response Message Bodies

Successful requests will generally return an HTTP status code of 200 (OK) to indicate that the requested action has been successfully performed. In addition, they might include a response message body (with an appropriate media type) containing a representation of the requested information. However, it is possible for a number of things to go wrong. The various underlying causes are described (as discussed in the previous section) by various HTTP status codes in the range 400-499 (for client side errors) or 500-599 (for server side problems). The description of each request type SHOULD list the possible status codes returned by that request type.

If a response is returned with an error status code (400-499 or 500-599), the server SHOULD also return a response message body containing a Messages data model, containing zero or more message data models, describing what went wrong. The text values of such messages might be used, for example, to communicate with a human user of the client side application.

Data Models

Note that these data models, while discussed in the context of reporting error conditions, are also suitable for a general event logging interface, and might get additionally purposed for this use at some point in the future.

Messages Data Model

The entire list of messages included in a single error response are encapsulated in a messages data model. The media type is application/vnd.com.esha.data.Messages+json

Field Name Type Occurs Description
message Message[] 1 Zero or more Message data models for each individual message.

Message Data Model

An individual message contains the following fields:

Field Name Type Occurs Description
action String 0..1 Symbolic identifier of the action being performed by the service implementation that triggered the creation of this message.
code String 0..1 Symbolic error code identifying the type of error reported by this message.
field String 0..1 Name of the input field (from the request data model) that this message is associated with. If not specified, this message should be considered global to the entire request.
hint String 0..1 Localized text further describing the nature of the problem, possibly including potential workarounds that the client could try.
severity String 0..1 Label indicating the severity of the error condition represented by this message (SEVERE, WARNING, CONFIG, INFO, FINE, FINER, FINEST).
source String 0..1 Symbolic identifier of the service implementation component that triggered this message.
stack-trace String 0..1 Stack trace associated with this message.
text String 1 Localized text describing the nature of the problem reported by this message.

version 8 as of 2 years ago by Christopher Elkins