The tastyTopia API represents a live, real-time view of the rich dataset that orderTopia holds. This document provides information to developers and other interested parties about our domain model and how to integrate with orderTopia.
tastyTopia provides a REST-ful resource-oriented API that returns responses in the JSON format. In its simplest incarnation, you describe the resource or resources you're looking for, and we respond with the results.
The API is available at http://api.ordertopia.com:8080
, also called the API URI, or AURI. You can check the status of the API by making a GET
request for this page; if successful, it is currently operational. You can make requests to and will receive responses from this location.
At present, the API is public access but in beta. No authentication is required, although we will rate-limit excessive usage. Use it judiciously.
All requests must be prefixed by the AURI. After that, the general format of a request is:
/<resource>/[<action>|<id>].<format>[?[<filter>=<value>]&...[<filter>=<value>]]
Specifically, a request consists of:
- a resource, followed by
- exactly one of an action or a resource identifier;
- concatenated by
.
to a format; - followed by zero or more filter-value pairs,
- the first such pair starting with
?
and subsequent ones starting with&
, - and each such pair consisting of a filter concatenated by
=
with its corresponding value.
- the first such pair starting with
field | description | format | example |
---|---|---|---|
resource | One of the tastyTopia resources. | string | "customers" |
action | Action to perform. Must be one of the supported actions. | string | "list" |
id | An identifier for the resource specified. | number | 500 |
format | Format to respond in. Must be one of the supported formats. | string | "json" |
filter | Filter to apply to results. Must be one of the supported filters. | string | "limit" |
value | Value to pass to this filter. | (varies; see filters) | 100 |
A request is said to be conforming if it meets the above specification. Nonconforming requests might still be accepted, but we don't make any promises. A request is said to be valid if it has acceptable values, regardless of syntax. A request is called correct if it's both valid and conforming. Note that a correct request might still result in a failure response -- for example, if you ask for a resource that doesn't exist.
Here are some examples of different requests:
http://ordertopia.com/foo/5.json
: Invalid; requests must start with the AURI.http://api.ordertopia.com:8080/foo/5.json
: Invalid;foo
is not an orderTopia resource.http://api.ordertopia.com:8080/merchants/json.5
: Non-conforming;id
should come beforeformat
.http://api.ordertopia.com:8080/merchants/5.json
: Correct. Retrievesmerchant
resource withid
5 in thejson
format.http://api.ordertopia.com:8080/merchants/list.json?limit=10
: Correct. Lists the first 10merchant
resources.
The following actions are supported:
list
: List all matching resources.
The following formats are supported:
json
: Standards-compliant JavaScript Object Notation.
Part of the headers you receive back in any tastyTopia response will be a HTTP status code. There are several possibilities for this value:
status code | name | description |
---|---|---|
200 | Success | You asked for a resource or resources. Here you go! |
300 | Multiple Choices | You asked me for something, but you weren't specific enough. Which one of these did you mean? |
400 | Bad Request | You have a syntax error or errors, or something else is wrong about what you asked me to do. |
401 | Unauthorized | (Not used yet.) You didn't supply appropriate credentials. |
403 | Forbidden | You are not authorized to make that kind of request. |
404 | Not Found | The resource you described doesn't match anything I know about. |
500 | Server Error | Something went wrong, so I can't give you what you asked for right now. Sorry about that. |
501 | Not Implemented | I understood your request, but I don't support that kind of request right now. |
503 | Service Unavailable | I'm not able to respond to requests right now. |
A code of 200 indicates success. Anything else means that there was a problem with the request.
When you receive a response, the body will contain a top-level response object, in JSON form. It will have the following general structure:
{
"count": ...,
"resource": ...,
"params": ...,
"results": [
...
]
}
These fields have the following meaning.
field | description | format | example |
---|---|---|---|
resource | Type of results you will get; will be one of {"primitive", [resource], "error"}, where [resource] is the name of any tastyTopia resource. | string | "resource": "customers" |
count | Number of results returned. | number | "count": 5 |
params | Parameters that were received from your request, in the form of a map of key-value string pairs. | object | "params": {"id": 6} |
If you receive a HTTP 200 header, your request was successful and tastyTopia was able to give you what you asked for. Your response will contain a resource array populated with the results. Here is an example of a successful request and response:
http://api.ordertopia.com:8080/merchants/100.json
HTTP/1.1 200 OK
Date: Wed, 03 Feb 2010 19:01:14 GMT
Server: Apache/2.2.3 (CentOS)
Pragma: no-cache
Cache-Control: no-cache
Content-Length: 191
Connection: close
Content-Type: application/json; charset=utf-8
{
"count": 1,
"resource": "merchants",
"params": {"id": "100"},
"results": [
{
"url": "http://ordertopia.com/merchants/tastytaters",
"description": "Tasty Taters sells a variety of scrumptiously starchy tubers!",
"id": 52,
"title": "Tasty Taters"
}
]
}
If you receive any header other than HTTP 200, your request was not necessarily successful:
- If your response object has a resource of
error
, then your request failed. - Otherwise, it was successful (see Successful Responses above).
If your request failed, the response will contain one or more errors which you may consult for additional information.
Resources form the vocabulary of things you can work with in tastyTopia.
Merchants are businesses which operate stores. They earn income by selling their products to customers.
field | description | format | example |
---|---|---|---|
id | Merchants's unique identifier. | identifier | 10 |
title | Merchant's business name. | string | Tasty Taters, Inc. |
url | Merchant's primary website. | string | http://ordertopia.com/merchants/tastytaters |
description | Short textual description of merchant and its offerings. | string | Tasty Taters offers scrumptiously starchy tubers of all kinds! |
Categories are arbitrary, merchant-defined groupings of products. Typically, merchants categorize products according to similarity in function or type. Categories may have a parent category.
field | description | format | example |
---|---|---|---|
id | Category's unique identifier. | identifier | 30 |
merchant_id | Merchant that this category belongs to. | identifier | 60 |
name | Name of this category. | string | "Cold Beverages" |
parent | The parent id of this category. | identifier | 29 |
A Customer is an individual person who purchases from a merchant's stores. The same user may represent many customers, each with a different presence at a different merchant.
field | description | format | example |
---|---|---|---|
id | The customer's unique identifier. | identifier | 40 |
first_name | Customer's first name. | string | Alice |
last_name | Customer's last name. | string | Waithersford-Humphreys |
street_address | Customer's mailing address. | string representing a mailing address | 1 OrderTopia Drive, Charlottesville, VA 22901 |
phone_number | Customer's primary phone number contact. | string representing a phone number | +1-567-890-0123 |
Customer's designated e-mail address. | string representing an email address | alicew@example.com |
Products are the offerings of a merchant to their customers. Complex products may require customers to make some choices about their contents, in which case they will have one or more slots.
field | description | format | example |
---|---|---|---|
id | The product's unique identifier. | identifier | 50 |
name | Short name for the product. | string | Tater Volcano |
description | Description of the product. | string | A scrumptious but geologically unstable starchy treat, smothered with your choice of gravy or cheese. |
categories | Categories that this product belongs to. | array of identifiers | [2, 8, 15] |
slots | Slots present on this item. | array of slots | (see slot section) |
Slots represent decisions that can be made about a product, like what kind of toppings to get on a sundae. A slot is filled with other products (which themselves can also have slots!). Which products may go in a slot depend on the categories specified by that slot. The number of products matching that specification that may go into a slot is determined by the slot's minimum and maximum size.
field | description | format | example |
---|---|---|---|
min | Minimum number of items that may go in this slot. | number | 0 |
max | Maximum number of items that may go in this slot. | number | 5 |
categories | Product categories which may fill this slot. | array of identifiers | [83, 86, 199] |
Stores are a merchant's physical or online presences, through which they sell products. Presently, each merchant has only one store.
These resources aren't true domain resources in orderTopia, but they're nonetheless important.
Errors are simply vehicles for delivering information about errors.
field | description | format | example |
---|---|---|---|
msg | Message payload for this error. | string | "filter 'mechant_id' is not a valid filter; did you mean 'merchant_id'?" |
The following filters with these values are supported:
filter | description | format | filtered count? |
---|---|---|---|
limit = n |
Return no more than n items. |
number | no |
offset = n |
Return items beginning at the n+1 th item. |
number | no |
category_id = n |
Return anything tagged with this category. | identifier | yes |
merchant_id = n |
Return anything tagged with this merchant. | identifier | yes |
When you apply some filters, the count
field in your response may be different from the number of items in the results
collection. This is done so that you know how many additional results are available that matched your base request, which is helpful when paging through long requests. Filters with this property are identified above with a "no" entry in the "filtered count?" column, and are called non-reducing filters.
In such cases, the count
field will be equal to the number of results that would have been returned had you not applied any non-reducing filters.