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.
& 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?
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
API Development a lot easier » If another group of developers are interacting with your API » They will have interactive, detailed documentation at their fingertips
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
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
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
ע מ י י ם נ ק ו ד ת י י ם ) 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...
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"
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