azurestandard/api-spec — pull request #3 by wking (2014-11-27 05:23:31+00:00)
Title: public.json: Add /products and /product/{code}

Based on the schema Jordan and Casey have [outlined][1]:

{
id:
name:
canonical_uri:
slug:
description:
brand:
status:
discount:
ingredients:
favorite_count:
images: []
variations_retail: [{
code:
size:
price:
stock:
}]
variations_wholesale: [{
code:
size:
price:
stock:
}]
date_created: // used to determine new products??
}

Changes from their schema:

* Replaced 'id' and 'slug' with 'code', since "product code"
(e.g. GR061) is the usual way we refer to products. I'd be fine
using IDs instead, but codes are so ingrained in user workflows and
it's not worth breaking those habits.
* Dropped 'canonical_uri', because I'm not convinced HATEOAS is worth
it (see azurestandard/beehive@deb2e28f, apps/api/views/drops.py:
Adjust to match the current API spec, 2014-11-20).
* Dropped 'status', because I'm not clear on how that's going to work
yet. We can have multiple statuses for a given product. Do we just
want to list status IDs, and have a separate endpoint where folks
who care about the statuses can go to get those details? Do we want
to embed those details in the product response? We can add this
back once the model and UI is clearer.
* Dropped 'ingredients', because I'm not clear on how that's going to
work yet. Do we want a list of ingredient IDs? IDs with names?
Just names? We can add this back in once the model is clearer.
* Renamed 'favorite_count' to 'favorites', and explain that it's a
count in the description. Not much reason for this, but it felt
better to me.
* Consolidated 'variations_retail' and 'variations_wholesale' into
'repackaged', which just links to the alternative sizes by product
code. For views that need this information (just the product-detail
view?), hitting the /product/{code} endpoint a few extra times will
be fast, and using minimal references avoids duplication in the API
and makes for lighter-weight responses for /products. Since I'm no
longer bundling the alternative size/price/..., I've included that
information in the root product object. The distinction between
retail and wholesale pricing is important, but like discount
statuses, it's better to handle that separately using a pricing API
and keep the product API simpler (only listing retail prices for
unauthenticated or retail customers, and only listing wholesale
prices for wholesale customers).
* Dropped 'date_created', because we should be handling new products
via status tags (once we handle statuses).

[1]: https://github.com/azurestandard/website/blob/71f01fa4cc41acbfd3abb921b22875ea15c069e3/docs/api.md#product-1