How (not) to build
APIs
Denys Yahofarov
senior developer
Slide 2
Slide 2 text
denyago@ wherever
Slide 3
Slide 3 text
API == HTTP API*
* at least in this talk
Slide 4
Slide 4 text
Development process is pleasure
Credits: https://flic.kr/p/9Ep15Y
Slide 5
Slide 5 text
Alien code is pain
Credits: http://i.iscute.com/7j7
Slide 6
Slide 6 text
How to cook?
Slide 7
Slide 7 text
How to cook?
5340 results
Slide 8
Slide 8 text
I’ll show how NOT to
build APIs
Slide 9
Slide 9 text
… as I had a lot of
mistakes
Slide 10
Slide 10 text
Building app from scratch
… client wants to have a dog adoption app
… and gives us as much time as we need
Credits: https://flic.kr/p/8rw6vC
Slide 11
Slide 11 text
#1. Let’s get to work!!!
Slide 12
Slide 12 text
No content
Slide 13
Slide 13 text
No content
Slide 14
Slide 14 text
No content
Slide 15
Slide 15 text
No content
Slide 16
Slide 16 text
No content
Slide 17
Slide 17 text
No content
Slide 18
Slide 18 text
No content
Slide 19
Slide 19 text
No content
Slide 20
Slide 20 text
No content
Slide 21
Slide 21 text
No content
Slide 22
Slide 22 text
No content
Slide 23
Slide 23 text
No content
Slide 24
Slide 24 text
What’s wrong?
• No design made
• No tests written
• No documentation
Slide 25
Slide 25 text
How do I do it now?
• Design Driven Development
• API Blueprints
• Behavior and Test Driven Development
• Documentation is auto-generated
• … and built from tests
jq is a
lightweight and
flexible command-line
JSON processor
Slide 54
Slide 54 text
What’s wrong?
• Presumption, that nothing gonna
change
• Changes not backward compatible
• No API version
Slide 55
Slide 55 text
How do I do it now?
• Always start with ‘v1’
• Never delete or change anything in
production versions
• Maintain “v_current_” and “v_previouos_”
• While developing “v_new_”
• … and have tests for both
Slide 56
Slide 56 text
One of ways
Slide 57
Slide 57 text
bploetz/versionist
… or
Slide 58
Slide 58 text
#4. We need strong
SECURITY!!1
Slide 59
Slide 59 text
No content
Slide 60
Slide 60 text
some
Voodoo Magic
Slide 61
Slide 61 text
No content
Slide 62
Slide 62 text
No content
Slide 63
Slide 63 text
No content
Slide 64
Slide 64 text
What’s wrong?
• Custom algorithm to verify messages
• Clients need to implement it on their
own
• The secret key can’t be revoked from
single client
Slide 65
Slide 65 text
How do I do it now?
• HTTPs
• oAuth 2.0, Resource Owner Password
Credentials Grant
• Sending token as a header
• Rails MessageVerifier for sharing
“one-time” or “time-limited” links
• … or just simple HTTP Authentication
Slide 66
Slide 66 text
No content
Slide 67
Slide 67 text
#5. JSON as a data
source
Slide 68
Slide 68 text
No content
Slide 69
Slide 69 text
No content
Slide 70
Slide 70 text
No content
Slide 71
Slide 71 text
oO
WAT?
Slide 72
Slide 72 text
No content
Slide 73
Slide 73 text
What was wrong?
• Different fields in index and show
• “Magic numbers” in JSON
• empty
(could be ‘date not in ISO8601
format’)
Slide 74
Slide 74 text
How do I do it now?
• All “Magic numbers” in databases
are mapped to user-readable names
• Use Serializers instead of templates
• Use ‘partial request’ to specify the set
of fields I want to get
• Time is always in UTC and ISO8601
format
Slide 75
Slide 75 text
#6. Querying and
filtering
Slide 76
Slide 76 text
No content
Slide 77
Slide 77 text
No content
Slide 78
Slide 78 text
No content
Slide 79
Slide 79 text
3 sec
Slide 80
Slide 80 text
No content
Slide 81
Slide 81 text
No content
Slide 82
Slide 82 text
No content
Slide 83
Slide 83 text
No content
Slide 84
Slide 84 text
Imagine your client app
… as a hamster
Credits: https://flic.kr/p/bGWME
Slide 85
Slide 85 text
What was wrong?
• No default limit
• Parser of parameters needs an array
to find all those IDs
• I used to have a count for all the
results. Sometimes there were
millions of results
Slide 86
Slide 86 text
How do I do it now?
• Default limit
• If limit loo big - return 4xx error
• Put filtering under a common name
(q[]= or search[]=)
• Have a toggle parameters for HTTP
clients with quirks
Slide 87
Slide 87 text
So…
• Have API documentation (auto-generated)
• Do only things required from you
• Use versioning
• Don’t re-invent authentication flows
• Let JSONs be verbose and consistent
• Limit data, returned to client
Slide 88
Slide 88 text
What is it?
Credits: https://flic.kr/p/6nei23
Slide 89
Slide 89 text
Dog food
Would you eat the one, you produce?
Credits: https://flic.kr/p/6nei23
Slide 90
Slide 90 text
Eat your own dog food
Slide 91
Slide 91 text
Fortumo
• Most of APIs used by us internally
• Cloud on top of several other clouds
• Many internal products, never seen by
customers