We started FoxyCart.com in 2007 and soon after slapped together some XML and called it an API. As our customer base grew and third-party integrations emerged, the need for a true REST API became a priority. Beginning in 2012, we started researching best practices for modern API development. This talk will tell the story of that research and 10-months of development that followed. You'll get a look at the HAL hypermedia format along with some best practices we came up with for our problem domain of exposing our entire admin interface. We'll cover a lot. You may need a seat belt.
3. What...
FoxyCart
● ecommerce shopping cart system
● Started by Brett Florio and myself in
2005/2006, incorporated in 2007.
● SaaS (soon to be PaaS)
● Built to integrate using your css/html (we're
not a CMS)
● No duplication of data
4. Why...
No duplication? Expose our data!
POX: Plain Old XML
● Confusing API actions
○ transaction_get, transaction_list, attribute_save, attribute_delete,
transaction_modify, store_includes_get, etc
● Confusing request/response model
● Tight coupling between the client and server
5. APIs and the Internet
● Middleware ($$$)
● RPC
● SOAP
● WSDL
● Web Services (the WS-* stack)
Tight Coupling!
Does your browser do this?
6. REST to the rescue
CRUD can be standardized via HTTP methods:
POST/PUT = create
GET = read
PATCH/PUT = update
DELETE = delete
(goodbye *_list, *_save, *_modify, etc methods)
7. REST to the rescue
Agreed upon response codes
● 1xx: Informational
● 2xx: Success
● 3xx: Redirection
● 4xx: Client Error (You Screwed Up)
● 5xx: Server Error (We Screwed Up)
http://en.wikipedia.org/wiki/List_of_HTTP_status_codes
8. But... where do we start?
What's a perfect example of a REST API?
9. What is REST anyway?
Six Constraints:
● Client-server
● Stateless
● Cacheable
● Layered system
● Code on demand (optional)
● Uniform interface
○ Identification of resources
○ Manipulation of resources through these representations
○ Self-descriptive messages
○ Hypermedia as the engine of application state
11. What's a media type?
Examples:
application/json
application/xml
application/hal+json
Originally defined as MIME types (RFC 2046)
Also referred to as Content-Types
12. Platform = Will Not Break
Ecommerce site broken at 4am and you
changed nothing?
No one wants that phone call.
14. Flexible Versioning
● FOXYCART-API-VERSION header
● Per-resource vendor specific media type:
application/vnd.foxycart.com.store.v1+json
See: http://www.foxycart.com/blog/the-hypermedia-debate
15. Flexible Versioning
● FOXYCART-API-VERSION header
● Per-resource vendor specific media type:
application/vnd.foxycart.com.store.v1+json
● Hypermedia allows us to version via the link
relation we code to.
16. Flexible Versioning
● FOXYCART-API-VERSION header
● Per-resource vendor specific media type:
application/vnd.foxycart.com.store.v1+json
● Hypermedia allows us to version via the link
relation we code to.
link: <https://example.com/users/2>;
rel="https://example.com/rels/user"
17. Flexible Versioning
● FOXYCART-API-VERSION header
● Per-resource vendor specific media type:
application/vnd.foxycart.com.store.v1+json
● Hypermedia allows us to version via the link
relation we code to.
link: <https://example.com/users/2>;
rel="https://example.com/rels/user"
link: <https://example.com/customers/2>;
rel="https://example.com/rels/customer"
21. Next...?
<link rel="self" href="https://api-sandbox.foxycart.com/" title="Your API
starting point."/>
<link rel="https://api.foxycart.com/rels/create_client" href="https://api-
sandbox.foxycart.com/clients" title="Create a client via POST."/>
HATEOAS:
Hypermedia as the Engine of
Application State
26. Examples!
Let's take a look at the HAL Browser!
Hal Talk:
http://haltalk.herokuapp.com/explorer/hal_browser.html#/
Foxy Cart:
http://wiki.foxycart.com/v/0.0.0/hypermedia_api
https://api-sandbox.foxycart.com/hal-browser/hal_browser.html#/
https://api-sandbox.foxycart.com/hal-browser/
27. What's all this token stuff?
* image credit: http://www.ibm.com/developerworks/library/x-androidfacebookapi/
28. OAuth 2.0 - Why Bother?
Remember: Platform as a service!
● Hosted solutions
● Hosted CMS
● Self-hosted on a development platform
Simplify where we can:
● If you created it, you get full access to it and
we can skip the OAuth Dance
30. REST is easy, right? (Nope)
● Should every resource have a custom media
type?
● How should Hypermedia be represented in
JSON (Collection+JSON, HAL, Siren, etc)?
● Link header exclusively or links as part of the
body?
● To embedded sub resources?
● PATCH/PUT or POST? (X-HTTP-Method-
Override)
● Where to put the version number?
31. REST is easy, right? (Nope)
● Include the full resource response when
creating or use a 204?
● How do you avoid one PATCH stomping
another?
○ ETags and Preconditions
○ "If-None-Match: W/"9f55f4d0f19b152a6e7c6ddeb4107e486fd7727c""
○ "If-Modified-Since: Wed, 15 Feb 2012 12:53:52 -0800"
● How do you make hypermedia useful to the
client and end user?
● Forms?
32. YOU NEED TESTS!
Functional tests are critical
● Ensures your changes haven't broken
anything old or new
● Speeds up prototyping
Tests are NOT a substitute for your eyeballs