Mike Adler, Constant Contact VP Engineering, discusses the history of APIs, and best practices that developers need to consider when building or consuming APIs. Mike made this presentation at the 2014 Ultimate Developer Event.
Share your thoughts on what goes into building a world-class API, or, what you need from an API as a developer in the comments below.
Very nice talk! As Mike said, I think the biggest challenge I’ve seen with APIs is not understanding what it is you’re building and why. For example, why are you choosing REST over a REST-like, RPC, or SOAP API? And when choosing REST, do you understand what it is and what the constraints are? It’s important to note that REST is by definition stateless, so are you going to utilize hypermedia to transmit application state (or HATEOAS, a requirement of REST as defined by Fielding)?
I’m also a fan of Spec Driven Development for APIs, and using a spec such as RAML to design your API- similar to how Mike said start with the documentation, except it is a step further removed. This lets you design your API visually while incorporating agile UX, mock it and get real user (and use case) feedback, and have a single source for API documentation, sharing, and interaction – all before writing a single line of code.
It’s of course important to adhere to the other best practices (using nouns for resources, CRUD, HTTP Status Codes, etc), but the design aspect in my opinion is the foundation of the API, and no matter what else you do – with a poor design your API will be short-lived. It’s also important to forego the mistake of going into your API with a version-first mindset – or as I like to say, versioning is a necessary evil. You should really only version your API in very, very limited cases. So plan for it, but plan to avoid having to do it for quite some time.
Mike, thanks for a great presentation! Very informational and entertaining, and thank you for opening up the blog for additional thoughts/ comments!