µCon '14: Building Beautiful APIs

In this talk Brendan McAdams will explore the concepts behind how to build good APIs that make sense, are easy for you and your users to work with, what to do, what not to do. Expect conversation about errors, documentation, and porcine cosmetics.

Transcript

1. Building Beautiful APIs (you've got red on you) µCon '14 Brendan McAdams ( @rit ) bmcadams@netflix.com
2. Beauty Is In The Eye Of The Beholder
3. ... But you can't always put lipstick on a pig and get good results.
4. Beautiful APIs Should Speak For Themselves » If your code & API are hard to understand internally it's likely the same externally » Is it monolithic and slow moving, or small and nimble? » Is it well documented? » Do you return well articulated, meaningful errors?
5. Smaller is Better » Build lots of small services » Move quickly, move independently » APIs are powerful in this model » API can feed UI, Data Services, etc without a monolithic dev cycle
6. Think Hard About Authentication » Central authentication with shareable tokens is important » Make sure you can restrict who has access to what resources (authorization / authz)
7. Choose a good service model » Choose a service model that's easy to interact with (and develop) » The same goes for your data layer, and development framework » Your Mileage May Vary, but I happen to think quite fondly of JSON & REST
8. Code Is Communication » Good Code should be Self Documenting » But there are also tools that can help » Apiary » Swagger
9. A Little Swagger In Your Step » Swagger can make API Development a lot easier » If another group of developers are interacting with your API » They will have interactive, detailed documentation at their fingertips
10. A Little Swagger In Your Step » Swagger is built around self documenting code » Documentation is always up to date. » Swagger itself is mostly a JSON based "Specification" » Scalatra module for describing API, generates JSON » swagger-ui JSON Frontend explores API
11. ERRORS » Errors! » Errors! » Errors!
12. ERRORS » Meaningless error messages lead to long days of slaving over error logs » Nothing sucks more than spending an hour digging through logs... » ... only to find it was something you could have communicated with an error message
13. Good Practices for Errors » If you can validate an entire request object, do so » Return every error you know about immediately, and clearly » If you can pass multiple errors up your stack and return them, do so... » JSON Supports Arrays, after all
14. Good Practices for Errors » Provide useful data, not a generic 500 Internal Server Error » If you have an exception, extract a message from it » However: Exceptions are not flow control
15. Provide Errors That Make Sense » PHP Provides this useful error message: » Parse error: syntax error, unexpected T_PAAMAYIM_NEKUDOTAYIM » W. T. F. ?
16. Provide Errors That Make Sense » 'Paamayim Nekudotayim' ( פ ע מ י י ם נ ק ו ד ת י י ם ) is apparently Hebrew for "Double Colon" » The main authors of PHP 4+ are Israeli, and probably thought this was funny. » Imagine how many hapless devs have misplaced '::' and spent hours scratching their heads...
17. Sensible Errors » Most API platforms have some sort of Status Code mechanism » For REST, Pick & Document HTTP Codes » BE CONSISTENT
18. Sensible Errors » Even if you make up your own silly HTTP codes, make sure you document them so people know what they mean. » There's a proposed HTTP Error Code "759 - Unexpected T_PAAMAYIM_NEKUDOTAYIM" » I also like "763 - Under- Caffeinated"
19. Testing Your API » Your API Framework of choice should provide good tools for testing it » If it doesn't, consider finding a better framework » Scalatra (the framework I'm using) provides great bindings to Scalatest » This contributes greatly to feeling comfortable that what you've built works as documented
20. Write Lots of Tests » Positive Tests » Negative Tests » Service Level Tests (HTTP Calls) » Helper Level Tests (backend objects sans HTTP) » Parser Tests » Regression Tests » Voight-Kampff Tests
21. One Test, Two Test, Red Test, Blue Test...
22. "Never Trust A Test You Haven't Seen Fail." - Rob Fletcher ( @rfletcherEW ) ... who says he nicked it from @tddmonkey (Colin Vipurs)
23. Questions?