Tweet
Tweet

Slide 1

Slide 1 text

Designing APIs @honzajavorek honzajavorek.cz Honza Javorek apiary.io

Slide 2

Slide 2 text

Day Night apiary.io Czech Python Community Mascot python.cz Spaghetti Code Hunter

Slide 3

Slide 3 text

how does the Ideal WEB API look like? Designing APIs...

Slide 4

Slide 4 text

use HTTP verbs: PUT, POST, DELETE! nouns in plural, not verbs! use 4xx error codes! use media types! provide filtering, sorting, pagination! versioning! JSON! CRUD × use cases! do not just expose database tables as resources! pretty URLs!

Slide 5

Slide 5 text

HmM... no.

Slide 6

Slide 6 text

backward compatible perfectly documented available exposes enough to satisfy my use case easy to learn consistent easy to use

Slide 7

Slide 7 text

DX Architecture Protocol

Slide 8

Slide 8 text

DX Architecture Protocol { { good framework could do for you ART × CRAFT can't be automated

Slide 9

Slide 9 text

DX Architecture Protocol { { good framework could do for you can't be automated }API builders see just this

Slide 10

Slide 10 text

protocol

Slide 11

Slide 11 text

Architecture

Slide 12

Slide 12 text

DEVELOPER EXPERIENCE . . .

Slide 13

Slide 13 text

don't forget there are people, not machines

Slide 14

Slide 14 text

"One should not treat others in ways that one would not like to be treated." (the ethic of reciprocity)

Slide 15

Slide 15 text

Errors Learn how to properly do error responses and messages. github.com/blongden/vnd.error Documentation - make sure it is up to date (test it!) - provide the big picture (not just reference) Consistency - make decisions, and then stick to them

Slide 16

Slide 16 text

Errors Learn how to properly do error responses and messages. github.com/blongden/vnd.error Documentation - make sure it is up to date (test it!) - provide the big picture (not just reference) Consistency - make decisions, and then stick to them Dredd github.com/apiaryio/dredd Apiary

Slide 17

Slide 17 text

ARCHITECTURE . . .

Slide 18

Slide 18 text

DB × api DOMAIN LOGIC API AFFORDANCE AFFORDANCE X

Slide 19

Slide 19 text

AFFORDANCES beer example idea by Stephen Mizell Empty state Drink? No. Add beer? Yes. Complain? Yes. Half full state Drink? Yes. Add beer? Yes. Complain? Yes. Full state Drink? Yes. Add beer? No. Complain? No. Resource: a beer glass

Slide 20

Slide 20 text

Finite state machine

Slide 21

Slide 21 text

Finite state machine beer example idea by Stephen Mizell

Slide 22

Slide 22 text

REPRESENTATION of STATE in HTTP?

Slide 23

Slide 23 text

REPRESENTATION of STATE in HTTP? easy: the JSON document you send back and forth Representing state of the beer glass: {"fullness": 50}

Slide 24

Slide 24 text

BUT HOW TO REPRESENT TRANSITIONS IN HTTP? ? ? ? ? ? ? ? ? ?

Slide 25

Slide 25 text

TRANSITIONS IN HTTP ? ? ? ? ? ? ? ? ?

Slide 26

Slide 26 text

HYPERLINK since 1965

Slide 27

Slide 27 text

WEB A P I

Slide 28

Slide 28 text

No content

Slide 29

Slide 29 text

EVOL V ABLE Decoupled! No hardcoded URLs. Clients follow links and adapt to what is available.

Slide 30

Slide 30 text

Removed an edit link? Clients won't break. 1 request instead of 100? Clients won't break. Design of URLs? Doesn't matter. Versioning? No, sorry.

Slide 31

Slide 31 text

No content

Slide 32

Slide 32 text

DESIGNING AN API? 1. model your domain logic, semantic model (focus on resources, use cases, affordances) 2. draw a finite state machine 3. choose a suitable format (HTML, HAL, Siren, …) 4. explain your semantics (write a "profile") 5. build the API, build smart API clients

Slide 33

Slide 33 text

DESIGNING AN API? 1. model your domain logic, semantic model (focus on resources, use cases, affordances) 2. draw a finite state machine 3. choose a suitable hypermedia type (HAL, Siren, …) 4. explain your semantics (write a "profile") 5. build the API, build smart API clients Apiary Hyperdrive github.com/the-hypermedia-project/Hyperdrive API Blueprint, MSON apiblueprint.org, github.com/apiaryio/mson

Slide 34

Slide 34 text

THE WEB the most scalable and robust architecture humanity invented so far

Slide 35

Slide 35 text

REST OH, and by the w aY, this architectural style is called...

Slide 36

Slide 36 text

REST OH, and by the w aY, this architectural style is called... pro tip: when searching the web, look for hypermedia instead

Slide 37

Slide 37 text

IT's not a sil ver bullet as any other architectural style, REST has benefits and tradeoffs

Slide 38

Slide 38 text

"If you think you have control over the system or aren't interested in evolvability, don't waste your time arguing about REST." —— Roy T. Fielding http:/ /www.slideshare.net/royfielding/rest-in-aem

Slide 39

Slide 39 text

No content

Slide 40

Slide 40 text

No content

Slide 41

Slide 41 text

PROTOCOL . . .

Slide 42

Slide 42 text

HTTP

Slide 43

Slide 43 text

RTFM

Slide 44

Slide 44 text

Everything important is in RFCs. Do not rely on blog articles, read the specs. No fear! RFCs are human-readable text! Use API frameworks to do the heavy lifting. Do not miss RFCs 2324 and 7168

Slide 45

Slide 45 text

SO THE TEASER w as A SCAM? RFC 7231 section 4.1 RFC 5789 RFC 6902 RFC 7386 Please, do not begin with mastering HTTP! You should not. json-schema.org (…yes, it was!)

Slide 46

Slide 46 text

THANK YOU DX Architecture Protocol DX Architecture Protocol Your web API before this talk Your web API after this talk