fj/dzb-ordertopia-api-docs

Documentation for orderTopia's internal API.

tastyTopia API for orderTopia (version 0.1)

Introduction

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.

Making API requests

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.

Address

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.

Authentication

At present, the API is public access but in beta. No authentication is required, although we will rate-limit excessive usage. Use it judiciously.

Request format

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.

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 before format.
• http://api.ordertopia.com:8080/merchants/5.json: Correct. Retrieves merchant resource with id 5 in the json format.
• http://api.ordertopia.com:8080/merchants/list.json?limit=10: Correct. Lists the first 10 merchant resources.

Supported actions

The following actions are supported:

• list: List all matching resources.

Supported formats

The following formats are supported:

• json: Standards-compliant JavaScript Object Notation.

HTTP status codes

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.

Responses

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}

Successful responses

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"
    }
  ]
}

Failed responses

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

Resources form the vocabulary of things you can work with in tastyTopia.

Merchants

Merchants are businesses which operate stores. They earn income by selling their products to customers.

Fields

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

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.

Fields

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

Customers

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.

Fields

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	[phone]
email	Customer's designated e-mail address.	string representing an email address	[email protected]

Products

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.

Fields

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

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.

Fields

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

Stores are a merchant's physical or online presences, through which they sell products. Presently, each merchant has only one store.

Special Resources

These resources aren't true domain resources in orderTopia, but they're nonetheless important.

Errors

Errors are simply vehicles for delivering information about errors.

Fields

field	description	format	example
msg	Message payload for this error.	string	"filter 'mechant_id' is not a valid filter; did you mean 'merchant_id'?"

Filters

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+1th 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.