Ask HN: API design practices
Hi HN,
I'm currently designing a couple of web services (1 will be for public use, another is mainly for mobile integration with an app I am developing but with possibility of opening it up for public consumption depending on what my client says).
Are there any resources from which I can read up on web design best practices/patterns? For example, how to handle versioning (compatibility between client and api). StackOverflow released an article documenting some of the lessons they learnt and they are fixing for the next version; more of this would be nice.
Essentially, what I am looking for is a checklist of things a Web Service API should have.
Regards, Daryl
Not specifically about web service APIs, but you might enjoy this talk by Joshua Bloch [1]:
"How To Design A Good API and Why it Matters": http://www.youtube.com/watch?v=aAb7hSCtvGw
> For example, how to handle versioning (compatibility between client and api)
Whatever you do, please have a distinguishable api versioning.
i.e:
example.com/api/1.0/
or:
api.example.com/1.0/
In this way you can add other versions very easily (api.example.com/2.0/) and avoid clinet-side confusions.
This document was immensely helpful to me http://chaos.troll.no/~shausman/api-design/api-design.pdf