Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
Pragmatists Guide to Hypermedia
Search
Jason Harmon
December 10, 2015
Technology
0
84
Pragmatists Guide to Hypermedia
GIven at APIDays Paris 2015
Jason Harmon
December 10, 2015
Tweet
Share
More Decks by Jason Harmon
See All by Jason Harmon
Operational API Design Anti-Patterns
jharmn
0
200
Other Decks in Technology
See All in Technology
データマネジメントを支える武器としてのメタデータ管理
10xinc
2
890
業務で使えるかもしれない…!?GitHub Actions の Tips 集 / CI/CD Test Night #7
ponkio_o
PRO
24
7.1k
大規模なアジャイル開発の現場と技術負債 / Technical Debt
yoshiitaka
21
4.1k
依存ライブラリはどこに?
takesection
0
110
TypeScript Quiz (Encraft #12 Frontend Quiz Night)
uhyo
6
700
複数の LLM モデルを扱う上で直面した辛みまとめ
kazuyaseki
1
250
KubeCon EU: Unlocking new Platform Experiences with Open Interfaces
salaboy
1
380
CI/CDがあたりまえの今の時代にAPIテスティングツールに求められていること / CI/CD Test Night #7
k1low
12
3k
VSCode上からSlackにメッセージを送る拡張機能を作っている話
ebarakazuhiro
0
120
生成AIの不確実性と向き合うためのオブジェクト指向設計
tkikuchi1002
2
680
HoneycombとOpenTelemetryでオブザーバビリティに入門してみる
sumiren
2
160
現実世界の事象から学ぶSOLID原則
h0r15h0
24
10k
Featured
See All Featured
GraphQLの誤解/rethinking-graphql
sonatard
48
9.1k
GraphQLとの向き合い方2022年版
quramy
28
12k
CSS Pre-Processors: Stylus, Less & Sass
bermonpainter
352
28k
Why You Should Never Use an ORM
jnunemaker
PRO
50
8.6k
Automating Front-end Workflow
addyosmani
1353
200k
The Psychology of Web Performance [Beyond Tellerrand 2023]
tammyeverts
5
1.4k
StorybookのUI Testing Handbookを読んだ
zakiyama
10
4.5k
The Mythical Team-Month
searls
214
42k
[RailsConf 2023 Opening Keynote] The Magic of Rails
eileencodes
8
8.2k
4 Signs Your Business is Dying
shpigford
174
21k
Docker and Python
trallard
33
2.6k
Fashionably flexible responsive web design (full day workshop)
malarkey
397
65k
Transcript
A Pragmatist’s Guide to Hypermedia Adding value, not complexity J(a)son
Harmon (@jharmn) @paypal @braintreedev • 12/8/2015 @ApiDaysGlobal
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.
HATEOAS == Finite State Machine 3 What is Hypermedia? ©2015
PayPal Inc.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Rel examples: PayPal 13 Hypermedia Links ©2015 PayPal Inc.
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.
Rel: IANA Relationship Types 15 Hypermedia Links http://www.iana.org/assignments/link-relations/link- relations.xhtml ©2015
PayPal Inc.
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.
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.
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.
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.
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.
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.
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.
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.
Static Resource Relationships ©2015 PayPal Inc. Confidential and proprietary. 24
Lower Value Use Cases
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.
Static Resource Relationships: Exceptions ©2015 PayPal Inc. 26 Lower Value
Use Cases
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.
Thanks! @jharmn @paypal @braintreedev