How (not) to build APIs

Stop shooting your feet by making same old mistakes in API development. Contains fails and my advices how to avoid them.

1. How (not) to build APIs Denys Yahofarov senior developer
2. denyago@ wherever
3. API == HTTP API* * at least in this talk
4. Development process is pleasure Credits: https://flic.kr/p/9Ep15Y
5. Alien code is pain Credits: http://i.iscute.com/7j7
6. How to cook?
7. How to cook? 5340 results
8. I’ll show how NOT to build APIs
9. … as I had a lot of mistakes
10. 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
11. #1. Let’s get to work!!!
24. What’s wrong? • No design made • No tests written • No documentation
25. How do I do it now? • Design Driven Development • API Blueprints • Behavior and Test Driven Development • Documentation is auto-generated • … and built from tests
26. Tools
27. Credits: https://flic.kr/p/4ZUEPV, https://flic.kr/p/8gRAdg, https://flic.kr/p/5vGNkE
28. http://apiblueprint.org http://apiary.io API mock servers Blueprint tools http://www.mocky.io http://www.mockable.io
29. BDD and TDD • RSpec • RSpecApiDocumentation
30. Swagger
31. RSpecAPIDocumentation
32. #2. Add everything useful
42. What’s wrong? • Add a “cool” gem • Test only required behavior • … and frontend team can be smart in using ALL the gem’s features This is not wrong
43. Credits: http://www.amusement.net/2012/02/20/primary-bug/
44. Tools You Ain’t Gonna Need It
45. #3. It’s not gonna change
53. jq is a lightweight and flexible command-line JSON processor
54. What’s wrong? • Presumption, that nothing gonna change • Changes not backward compatible • No API version
55. 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
56. One of ways
57. bploetz/versionist … or
58. #4. We need strong SECURITY!!1
60. some Voodoo Magic
64. 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
65. 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
67. #5. JSON as a data source
71. oO WAT?
73. What was wrong? • Different fields in index and show • “Magic numbers” in JSON • empty (could be ‘date not in ISO8601 format’)
74. 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
75. #6. Querying and filtering
79. 3 sec
84. Imagine your client app … as a hamster Credits: https://flic.kr/p/bGWME
85. 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
86. 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
87. 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
88. What is it? Credits: https://flic.kr/p/6nei23
89. Dog food Would you eat the one, you produce? Credits: https://flic.kr/p/6nei23
90. Eat your own dog food
91. Fortumo • Most of APIs used by us internally • Cloud on top of several other clouds • Many internal products, never seen by customers
92. Eating lot of own ‘dog food’
93. Read books
94. Play and experiment
96. Look for new challenges* * yes, we are hiring too
97. Questions?
98. What is your favorite design or programming fail?
99. Thank you!