

Ask HN: API design practices - darylteo

Hi HN,<p>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).<p>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.<p>Essentially, what I am looking for is a checklist of things a Web Service API should have.<p>Regards,
Daryl
======
d_r
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>

[1] <http://en.wikipedia.org/wiki/Joshua_Bloch>

~~~
darylteo
Thanks

------
toni
> 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.

~~~
darylteo
Yes! I do have this planned (followed StackOverflow).

What I'm looking for is a resource where these kinds of things are pointed
out.

Any ideas regarding Authentication? Roll your own, or implement OAuth? When
would be a good time to use OAuth?

------
raquo
This document was immensely helpful to me
<http://chaos.troll.no/~shausman/api-design/api-design.pdf>

Related: <http://news.ycombinator.com/item?id=2796371>

