Ask HN: API design practices

4 points by darylteo 14y ago ↗ HN

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

5 comments

[ 4.8 ms ] story [ 46.4 ms ] thread

d_r 14y ago ↗

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 14y ago ↗

Thanks

toni 14y ago ↗

> 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 14y ago ↗

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 14y ago ↗

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