Pragmatists Guide to Hypermedia

GIven at APIDays Paris 2015

Transcript

1. A Pragmatist’s Guide to Hypermedia Adding value, not complexity J(a)son Harmon (@jharmn) @paypal @braintreedev • 12/8/2015 @ApiDaysGlobal
2. Who am I? 2 J(a)son Harmon • From Austin, TX • Head of API Design at PayPal • More focused on Braintree lately • Blogger at apiux.com, pragmaticapi.com • Organizer austinapi.com meetup • Youtube: API Workshop ©2015 PayPal Inc.
3. HATEOAS == Finite State Machine 3 What is Hypermedia? ©2015 PayPal Inc.
4. Problems ©2015 PayPal Inc. 4 Why all the drama? Common arguments: • State machines are hard • Resource size increases • Clients aren’t requesting hypermedia • “It’s more complicated” We need to think about adding value, and reducing complexity.
5. Solutions 5 Why all the drama? • State machines are hard • Use where value is added; don’t try to understand it all at once • Resource size increases • With gzip, it’s a surprisingly small footprint, when used conservatively • Clients aren’t requesting hypermedia • The best products add value customers hadn’t thought about; make the links add value • “It’s more complicated” • Let’s focus on cases where we can simplify things… ©2015 PayPal Inc.
6. Web vs API Persona l Send Request s Home 6 Web Hypermedia /payments ./{id} ./{id} ./ {id}/execute / authorizatio ns ./{id} API Hypermedia – Today’s examples What is Hypermedia? text/html text/html text/html text/html text/css image/svg+xml application/json ©2015 PayPal Inc.
7. Why no media types? application/json application/xml text/html application/x-www-form-url-encoded text/css image/png image/gif IETF/RFC-based • vnd.error+json • application/problem+json • application/status+xml 7 Standard browser mime types (generic) Message formats application/json+hal application/vnd.collection+json application/vnd.siren+json Company-specific application/vnd.mycompany+json Application/vnd.github.v3+json Custom media types It depends on which ones ©2015 PayPal Inc.
8. Why use custom media types? Clients can standardize on how to process messages Standardization of common API elements Examples: • Errors • Dates • Status 8 Pros Browsers & HTTP clients don’t know custom types • Potentially unpredictable results Added support cost/docs complexity Every message in a proprietary API potentially has a different media type Message formats must be invested in up-front Cons Why not? ©2015 PayPal Inc.
9. Why aren’t we doing custom media types for everything? Events Event.name.html Event.description.html Event.organizer_id Event.start_utc Event.start.timezone … 9 EventBrite Engagements Engagement.id Engagement.portalId Engagement.active Engagement.createdAt Engagement.lastUpdated Engagement.ownerId … HubSpot We’re all special and unique flowers ©2015 PayPal Inc.
10. application/json works 10 Postel’s Law AKA Robustness Principle is real Be conservative in what you send, be liberal in what you accept Most custom media types work if you just use application/json See RFC760 for more inspiration ©2015 PayPal Inc.
11. Custom Media Types: TL;DR 11 You probably should, but you probably won’t The value vs complexity is questionable (even though it’s technically superior) Darrel Miller says http://www.bizcoder.com/please-no-more- generic-hypermedia-types ©2015 PayPal Inc.
12. Common Structure • href – a URI/URL; where you want to go. Opaque to client. • verb – Not often utilized; how you should use the resource. • title – Also not common; provides client with a description. • rel – “relationship” • Client should bind code to ‘rel’, not href. • Essentially a unique key for the client to bind to their customer’s actions, relative to the resource. 12 Hypermedia links ©2015 PayPal Inc.
13. Rel examples: PayPal 13 Hypermedia Links ©2015 PayPal Inc.
14. Rel examples: HAL 14 Hypermedia Links Spec: https://tools.ietf.org/html/draft-kelly-json-hal-07 Real examples: http://Clarify.io http://FoxyCart.com ©2015 PayPal Inc.
15. Rel: IANA Relationship Types 15 Hypermedia Links http://www.iana.org/assignments/link-relations/link- relations.xhtml ©2015 PayPal Inc.
16. Rel: Why self?? • Really doesn’t look useful for the developer • Allows client to store the resource location when caching • When a refresh is needed later, it’s quite simple • A really easy entry into hypermedia • Zero state machine complexity Note: • Always respect incoming host header (true for all links) • Perfect example of why you should always use a full URI/URL, and not just path 16 Hypermedia Links ©2015 PayPal Inc.
17. Paging Controls The biggest opportunity to improve DX in your API. If you don’t do the heavy lifting of paging results, and producing links, your API clients will have to do it…likely inconsistent, and wrong. next previous first last 17 Hypermedia Links ©2015 PayPal Inc.
18. Paging Controls Caveats: • Maintain all query parameters; in case other features are being used (filters etc) • Don’t provide a `previous` link when it’s the first page • Don’t provide a `next` link when it’s the last page 18 Hypermedia Links ©2015 PayPal Inc.
19. Actions When non-CRUD (dare I say RPC-ish) resources are in play, they’re often high value • rel: best to name it the same as the action name 19 Hypermedia Links ©2015 PayPal Inc.
20. Encapsulate Permissions First, look for bit flags: • canUpdate • isAdmin Client is forced to interpret the meaning of Booleans to determine interaction • Better to provide a link, and hide the Booleans. • If the client is allowed to do something, they should get a link. • Again, if the client interprets Booleans, it may end up inconsistent or just plain wrong. 20 Hypermedia Links ©2015 PayPal Inc.
21. Encapsulate Permissions: Example • Can a client provide an action to refund? • `isRefundAvailable`: bad choice • Instead, provide a link to the resource if a refund is available: 21 Hypermedia Links ©2015 PayPal Inc.
22. CRUD verbs • Probably the best argument against including verb with links • Can create a large number of combinatorial links • Often there is no state involved, so it’s of marginal value /widgets • create: POST /widgets • update: PATCH /widgets • delete: DELETE /widgets Caveat: • When CRUD actions are conditional, their value rises, i.e. `canUpdate`, `canDelete` • The best argument FOR verbs  22 Lower Value Use Cases ©2015 PayPal Inc.
23. Static Resource Relationships Static resource relationships • Linking to every level of hierarchy • Child • Parent • Peers • Inter-domain links • If state never changes, this is much lower value • If the likelihood of using a link is low, think about eliminating it 23 Lower Value Use Cases ©2015 PayPal Inc.
24. Static Resource Relationships ©2015 PayPal Inc. Confidential and proprietary. 24 Lower Value Use Cases
25. Static Resource Relationships Caveat: • When one resource has close relationships to others (i.e. high value), it’s worth it. • This is especially true if you create multiple resources in one action. 25 Lower Value Use Cases ©2015 PayPal Inc.
26. Static Resource Relationships: Exceptions ©2015 PayPal Inc. 26 Lower Value Use Cases
27. Define value Reduces client complexity: • Features such as paging add a lot of overhead for clients. • Interpreting state to provide end user interaction is error prone. • Storing a configuration file full of URLs is painful for clients. More self-documenting • With a well chosen ontology, client developers can learn relationships and related actions without reading docs. Focus on links which augment client developer behavior 27 Summing it up ©2015 PayPal Inc.
28. Thanks! @jharmn @paypal @braintreedev