How (not) to build APIs

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.

9986d4cfe597f7ce12331ffdd75f471f?s=128

Denis Yagofarov

September 20, 2014
Tweet

Transcript

  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!!!

  12. None
  13. None
  14. None
  15. None
  16. None
  17. None
  18. None
  19. None
  20. None
  21. None
  22. None
  23. None
  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

  33. None
  34. None
  35. None
  36. None
  37. None
  38. None
  39. None
  40. None
  41. None
  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

  46. None
  47. None
  48. None
  49. None
  50. None
  51. None
  52. None
  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

  59. None
  60. some Voodoo Magic

  61. None
  62. None
  63. None
  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
  66. None
  67. #5. JSON as a data source

  68. None
  69. None
  70. None
  71. oO WAT?

  72. None
  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

  76. None
  77. None
  78. None
  79. 3 sec

  80. None
  81. None
  82. None
  83. None
  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

  95. None
  96. Look for new challenges* * yes, we are hiring too

  97. Questions?

  98. What is your favorite design or programming fail?

  99. Thank you!