From POX to HATEOAS by Luke Stokes

Transcript

1. From POX to HATEOAS The FoxyCart hAPI Story
2. Who... Luke Stokes Co-Founder, CTO of FoxyCart luke.stokes@foxycart.com @lukestokes
3. What... FoxyCart • Ecommerce shopping cart platform • Started by Brett Florio and myself in 2005/2006, incorporated in 2007. • Platform as a service • Built to integrate • When one-size-fits-all doesn’t fit
4. Why... • How many here have built an API? • How often do you have to refer to your own documentation when using the API you built?
5. We Can Do Better Build to integrate? 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
6. APIs and the Internet • Middleware ($$$) • RPC • SOAP • WSDL • Web Services (the WS-* stack) Tight Coupling! Does your browser do this?
7. REST to the rescue • CRUD standardized via HTTP methods • Standardized response codes via HTTP status methods ◦ 1xx: Informational ◦ 2xx: Success ◦ 3xx: Redirection ◦ 4xx: Client Error (You Screwed Up) ◦ 5xx: Server Error (We Screwed Up)
8. 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
9. REST Client Need-to-Know • Homepage • Hypermedia Format • Custom Link Relationships (rel tags) • Supported Media Types • Bonus Stuff: ◦ ?limit=5&offset=10 ◦ ?order=<field> desc (or asc) ◦ ?fields=<field>,<field>,<field> ◦ ?<field>=<value> ◦ ?<field>=<some * partial value> ◦ ?zoom=<resource>
10. Hypermedia Content Types • HAL • Siren • Collection • JSON-LD • X/HTML • Atom • vnd.yourcompany.com.resource+json application/json says nothing about hypermedia
11. ...With Benefits • OPTIONS (HTTP method) • Hypermedia as the engine of application state (follow the links!) • Flexible Versioning (if absolutely needed) ◦ required header: FOXY-API-VERSION: 1 ◦ versioned link relationship (“user” vs. “customer”, etc) • Data Consistency ◦ ETags and Preconditions (If-None-Match, If- Modified-Since)
12. OrderDesk
13. New FoxyCart Admin
14. Challenges • OAuth 2.0 • Error responses (vnd.error, hal, siren) • Why so many requests? • Emphasizing the importance of local cache, ETags, etc.
15. We humans learn by experience and examples, not by memorizing documentation. Hal Talk: http://haltalk.herokuapp.com/explorer/browser.html#/ FoxyCart: https://api.foxycart.com/docs https://api-sandbox.foxycart.com/hal-browser/hal_browser. html#/ https://api-sandbox.foxycart.com/hal-browser/ Examples!
17. Remove the token, follow self link
18. Create a client
19. Error response
20. View Docs
21. Copy and paste directly from the docs
22. OAuth tokens in the response
23. Connect with the new token, new affordance!
24. Coding to link relations https://api.foxycart.com Why Your Colleagues Still Don’t Understand Hypermedia APIs More coders thinking in hypermedia = more HAPI coders More HAPI coders building for hypermedia = more hypermedia tools and clients
25. Think in terms of link relationships...
26. hAPI adoption “It’s not REST if it’s not HATEOAS.” “Show me the hypermedia.” … But we teach developers to code to URLs (Swagger, I/O Docs, APIary, etc)
27. Tells developers to code to URLs
28. api.foxycart.com @lukestokes Will soon be known as...