ESHA Data API, Version 0.6

Introduction

This document specifies the RESTful API for interacting with the ESHA Data service.

Usage of the API is via the HTTP protocol. Resource representations are in JSON.

The specification of the ESHA Data API includes:

This API operates on the following primary resource types:

Specifications

Common Behaviors

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.

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).
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.

Error Response Message Bodies

Introduction

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.

Resource Models

This section specifies the representations of the resources which this API operates on. The representations are made up of fields, each with a name and value, encoded using a JSON dictionary. The values may be numeric or string literals, lists, or dictionaries, each of which are represented in the obvious way in JSON.

Food [application/vnd.com.esha.data.Food+json]

A Food represents a food in the database.

A “Food” resource model contains the following fields:

Field Name Type Occurs Description
id URI 1 The unique identifier of this food.
description String 0..1 Human friendly description of this food.
quantity Number 0..1 The scaling quantity for this food.
unit String 0..1 The identifier of the scaling unit for this food.
units String[] 0..1 The identifiers of the food units available for scaling this food.
group String 0..1 The primary group for this food.
product String 0..1 The product for this food.
supplier String 0..1 The supplier for this food.
nutrient_data NutrientDataPoint[] 0..1 The nutrient data for this food, scaled to quantity and unit.
modified String 0..1 The modification date (in ISO 8601 format) for this food.
discontinued Boolean 0..1 If present and true, the food has been discontinued.

Foods [application/vnd.com.esha.data.Foods+json]

A Foods represents a list of foods and is used primarily in the response from searching the database for foods and in a request to the analysis resource.

A “Foods” resource model contains the following fields:

Field Name Type Occurs Description
query String 0..1 The query used to perform a search that resulted in the matching items.
total Number 1 The total number of items available on all pages.
items Food[] 1 The current page of items.
first_page URI 1 The URI that may be used to retrieve the first page of items.
prev_page URI 0..1 The URI that may be used to retrieve the previous page of items, if applicable.
next_page URI 0..1 The URI that may be used to retrieve the next page of items, if applicable.

Food Analysis [application/vnd.com.esha.data.FoodAnalysis+json]

A Food Analysis represents the results of analyzing a collection of one or more foods.

A “Food Analysis” resource model contains the following fields:

Field Name Type Occurs Description
items Food[] 0..1 The input to the analysis.
results NutrientDataPoint[] 1 The results of the analysis.

Food Units [application/vnd.com.esha.data.FoodUnits+json]

The entire list of food units available in the database is included in a FoodUnits data model.

Field Name Type Occurs Description
N/A FoodUnit 0..n Zero or more FoodUnit data models
Food Unit Data Model

An individual food unit contains the following fields:

Field Name Type Occurs Description
id String 1 ESHA identifier for this food unit
description String 1 Human-friendly description of this food unit

Nutrients [application/vnd.com.esha.data.Nutrients+json]

The entire list of nutrients available in the database is included in a FoodUnits data model.

Field Name Type Occurs Description
N/A Nutrient 0..n Zero or more Nutrient data models
Nutrient Data Model

An individual nutrient contains the following fields:

Field Name Type Occurs Description
id String 1 ESHA identifier for this nutrient
description String 1 Human-friendly description of this nutrient
unit String 0..1 An optional unit label for this nutrient

Nutrient Data Point [application/vnd.com.esha.data.NutrientDataPoint+json]

A Nutrient Data Point represents a nutrient data point.

A “Nutrient Data Point” resource model contains the following fields:

Field Name Type Occurs Description
nutrient String 1 The identifier of the nutrient.
value Number 1 The value.

Service [application/vnd.com.esha.data.Service+json]

A Service represents the ESHA Data service itself.

A “Service” resource model contains the following fields:

Field Name Type Occurs Description
analysis URI Template 1 A template for building URIs to submit Foods for analysis.
food_units URI 1 A URI to list the FoodUnits this database contains.
foods URI Template 1 A template for building URIs to search the Foods this database contains.
nutrients URI 1 A URI to list the Nutrients this database contains.
specification_version String[] 1 Which version(s) of this specification this server implementation supports.
implementation_version String 1 Version of the server implementation.

Requests to Analysis Resources

The requests documented in this section are directed to Analysis resources.

Analyze a List of Foods for Nutrient Content

Synopsis:
POST {Analysis URI}
Request Parameters:
n
Request Headers:
Accept, Content-Length, Content-Type
Request Message Body:
Foods
Response Headers:
Content-Length, Content-Type
Response Message Body:
Food Analysis
Response Status:
200, 400, 500
Request Parameters
n
A comma-separated list of nutrient identifiers.
Example Request

Analyze the specified foods for the specified nutrients.

POST /analysis?n=0,1
Host: api.esha.com
Content-Type: application/vnd.com.esha.data.Foods+json
Content-Length: nnn
Accept: application/vnd.com.esha.data.FoodAnalysis+json

{
    "items" : [
        {
            "id" : "http://api.esha.com/foods/6757?query=broccoli&start=0&count=1&spell=true",
            "quantity" : 100,
            "unit" : "8"
        },
        {
            "id" : "http://api.esha.com/foods/5028?query=broccoli&start=1&count=1&spell=true",
            "quantity" : 100,
            "unit" : "8"
        },
        {
            "id" : "http://api.esha.com/foods/6193?query=broccoli&start=2&count=1&spell=true",
            "quantity" : 85,
            "unit" : "8"
        }
    ]
}
Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.com.esha.data.FoodAnalysis+json
Content-Length: nnn

{
    "results" : [
        {
            "nutrient" : "0",
            "value" : 1.234
        },
        {
            "nutrient" : "1",
            "value" : 2.345
        }
    ]
}

Search Foods

Conducts a search of the database for foods.

Synopsis:
GET {Foods URI}
Request Parameters:
query, start, count, spell
Request Headers:
Accept
Request Message Body:
N/A
Response Headers:
Content-Length, Content-Type
Response Message Body:
Foods
Response Status:
200, 400, 500
Request Parameters
query
The query used to search the database. TODO: Describe fields supported by the index.
start
The zero-based offset into the results. When used with the count parameter, you can request successive pages of results.
count
The maximum number of results to return. This number cannot be greater than 100. If not specified, the default value is 25.
spell
If “true” (the default value) or “1” and no matches are found, then the search will be re-tried with automatic spelling correction of the query.
Example Request

Search for “broccoli”.

GET /foods?query=broccoli
Host: api.esha.com
Accept: application/vnd.com.esha.data.Foods+json
Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.com.esha.data.Foods+json
Content-Length: nnn

{
    "query" : "broccoli",
    "total" : 93,
    "items" : [
        {
            "description" : "Broccoli, fresh",
            "group" : "Fresh Vegetables & Legumes",
            "id" : "http://api.esha.com/foods/6757?query=broccoli&start=0&count=1&spell=true",
            "quantity" : 100,
            "supplier" : "USDA SR-22",
            "unit" : "8",
            "units" : [ "3", "8" ],
        },
        {
            "description" : "Broccoli, chpd, ckd, drained",
            "group" : "Cooked Vegetables & Legumes",
            "id" : "http://api.esha.com/foods/5028?query=broccoli&start=1&count=1&spell=true",
            "quantity" : 100,
            "supplier" : "USDA SR-22",
            "unit" : "8",
            "units" : [ "3", "8" ],
        },
        {
            "description" : "Broccoli, florets, fzn",
            "group" : "Frozen Vegetables & Legumes",
            "id" : "http://api.esha.com/foods/6193?query=broccoli&start=2&count=1&spell=true",
            "quantity" : 85,
            "supplier" : "Birds Eye Foods",
            "unit" : "8",
            "units" : [ "3", "31", "8" ]
        }
        ...
    ],
    "first_page" : "/foods?query=broccoli&start=0&count=25&spell=true",
    "next_page" : "/foods?query=broccoli&start=25&count=25&spell=true"
}

List Food Units

List all known food units.

Synopsis:
GET {Food Units URI}
Request Parameters:
N/A
Request Headers:
Accept
Request Message Body:
N/A
Response Headers:
Content-Length, Content-Type
Response Message Body:
FoodUnits
Response Status:
200, 400, 500
Example Request

Retrieve a list of all known food units.

GET /food-units
Host: api.esha.com
Accept: application/vnd.com.esha.data.FoodUnits+json
Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.com.esha.data.FoodUnits+json
Content-Length: nnn

[
    {
        "id" : "1",
        "description" : "Teaspoon"
    },
    {
        "id" : "2",
        "description" : "Tablespoon"
    },
    {
        "id" : "3",
        "description" : "Cup"
    },
    ...
]

List Nutrients

List all known nutrients.

Synopsis:
GET {Nutrients URI}
Request Parameters:
N/A
Request Headers:
Accept
Request Message Body:
N/A
Response Headers:
Content-Length, Content-Type
Response Message Body:
Nutrients
Response Status:
200, 400, 500
Example Request

Retrieve a list of all known nutrients.

GET /nutrients
Host: api.esha.com
Accept: application/vnd.com.esha.data.Nutrients+json
Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.com.esha.data.Nutrients+json
Content-Length: nnn

[
    {
        "id" : "0",
        "description" : "Calories",
        "unit" : "kcal"
    },
    {
        "id" : "1",
        "description" : "Protein",
        "unit" : "g"
    },
    {
        "id" : "2",
        "description" : "Carbohydrates",
        "unit" : "g"
    },
    ...
]

Requests to Service Resources

The requests documented in this section are directed to Service resources, which allows a client to enumerate the service resources accessible to the user performing this request.

Get Service

Retrieve information about accessible resources.

Synopsis:
GET {Well Known URI of the Service}
Request Headers:
Accept
Request Parameters:
N/A
Request Message Body:
N/A
Response Headers:
Content-Length, Content-Type
Response Message Body:
Service
Response Status:
200, 400, 500
Example Request

Retrieve information about service resources.

GET /
Host: api.esha.com
Accept: application/vnd.com.esha.data.Service+json
Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.com.esha.data.Service+json
Content-Length: nnn

{
    "analysis" : "http://api.esha.com/analysis{-opt|?|n}",
    "food_units" : "http://api.esha.com/food-units",
    "foods" : "http://api.esha.com/foods{-opt|?|query,start,count,spell}{-join|&|query,start,count,spell}",
    "nutrients" : "http://api.esha.com/nutrients",
    "specification_version" :  [  "0.5"  ],
    "implementation_version" : "1.0.2"
}

Version History

0.1

0.2

0.3

0.4

0.5

0.6