Building Better Web APIs (PyCon AU 2014)

Slide 1

Slide 1 text

[email protected] @hawkieowl

Slide 2

Slide 2 text

No content

Slide 3

Slide 3 text

technicals.atleastfornow.net

Slide 4

Slide 4 text

Building Better Web APIs

Slide 5

Slide 5 text

Why do we need Web APIs?

Slide 6

Slide 6 text

APIs are how applications talk

Slide 7

Slide 7 text

Implement once, access anywhere

Slide 8

Slide 8 text

Break open the silo!

Slide 9

Slide 9 text

And it’s two way!

Slide 10

Slide 10 text

And can be automated!

Slide 11

Slide 11 text

The applications are massive

Slide 12

Slide 12 text

Web 3.0 The Internet Of Things

Slide 13

Slide 13 text

Web 3.0 The Internet Of Things

Slide 14

Slide 14 text

The Programmable Internet

Slide 15

Slide 15 text

No content

Slide 16

Slide 16 text

Rich APIs == Automation Wins

Slide 17

Slide 17 text

The Beneﬁts

Slide 18

Slide 18 text

Implementing Web APIs

Slide 19

Slide 19 text

Who are our users?

Slide 20

Slide 20 text

Design for the End User • Expose all the data that the user might need • Provide encrypted endpoints

Slide 21

Slide 21 text

Design for the Implementor • Design to the principal of least surprise and lay your resources out in a consistent way • Provide a platform which will cause little need for modiﬁcation down the line • Provide documentation which adequately and completely explains your API and its semantics - provide examples!!!!

Slide 22

Slide 22 text

Versioning

Slide 23

Slide 23 text

Explicit versions are essential for stability

Slide 24

Slide 24 text

Provide API Pinning

Slide 25

Slide 25 text

Pinning Methods • URI • route53.amazonaws.com/2013-04-01/hostedzone • Header • ‘Stripe-Version: 2014-06-17’ • ‘Accept: application/vnd.heroku +json; version=3’

Slide 26

Slide 26 text

Your version should be in your API’s URI

Slide 27

Slide 27 text

For example: v1.api.example.com (better)  api.example.com/v1/ (best)

Slide 28

Slide 28 text

–Tim Berners-Lee (http://www.w3.org/Provider/Style/URI.html) “Cool URIs don't change.”

Slide 29

Slide 29 text

/v1/resource == /v2/resource ?

Slide 30

Slide 30 text

Different versions have different responses and resource layout

Slide 31

Slide 31 text

Layout

Slide 32

Slide 32 text

Resources, not functions

Slide 33

Slide 33 text

/cakes/1 is better than /get_cake?id=1

Slide 34

Slide 34 text

/cakes is better than /get_all_cakes

Slide 35

Slide 35 text

POST to /cakes is better than POST to /make_cake

Slide 36

Slide 36 text

/cakes/1/layers/1 is better than /get_cake_layer?cake_id=1&layer_id=1

Slide 37

Slide 37 text

/cakes/1/layers/1/icing is better than /get_cake_layer_icing?cake_id=1&layer_id=1

Slide 38

Slide 38 text

REST

Slide 39

Slide 39 text

REST is best

Slide 40

Slide 40 text

REST maps state transforms to HTTP methods

Slide 41

Slide 41 text

REST in 2014 • GET fetches (RFC 7231) • POST is resource speciﬁc (RFC 7231) • PUT replaces or creates (RFC 7231) • PATCH updates (RFC 5789) • DELETE removes (RFC 7231)

Slide 42

Slide 42 text

Do what makes sense, be pragmatic!

Slide 43

Slide 43 text

But just in case, document it anyway

Slide 44

Slide 44 text

Documentation

Slide 45

Slide 45 text

Document side-effects

Slide 46

Slide 46 text

Don’t be afraid to copy good documentation styles

Slide 47

Slide 47 text

Stripe: Good!

Slide 48

Slide 48 text

Mailgun: Good!

Slide 49

Slide 49 text

Mailgun: Good!

Slide 50

Slide 50 text

Linode… not so good

Slide 51

Slide 51 text

Validation

Slide 52

Slide 52 text

Validation is great

Slide 53

Slide 53 text

On output, as well!

Slide 54

Slide 54 text

Django REST Framework: Use typed ﬁelds

Slide 55

Slide 55 text

JSON Schema is framework-agnostic

Slide 56

Slide 56 text

Speed

Slide 57

Slide 57 text

100 Continue can save time & bandwidth

Slide 58

Slide 58 text

…but you can’t use it with WSGI

Slide 59

Slide 59 text

Stateless workers for better scaling

Slide 60

Slide 60 text

My Research

Slide 61

Slide 61 text

Haddock https://github.com/hawkowl/haddock

Slide 62

Slide 62 text

Saratoga https://github.com/hawkowl/saratoga

Slide 63

Slide 63 text

Tool Improvements

Slide 64

Slide 64 text

Better tools mean better result for the same effort

Slide 65

Slide 65 text

Versioning

Slide 66

Slide 66 text

Validation

Slide 67

Slide 67 text

Documentation

Slide 68

Slide 68 text

Other things I couldn’t ﬁt inside 20 minutes…

Slide 69

Slide 69 text

Testing

Slide 70

Slide 70 text

RPC over REST

Slide 71

Slide 71 text

Authentication Methods

Slide 72

Slide 72 text

…but do ﬁt on a website

Slide 73

Slide 73 text

HawkOwl’s Technicals technicals.atleastfornow.net

Slide 74

Slide 74 text

Questions! Twitter: @hawkieowl