

Ask HN: How should I build my API? - relm86

I want to build an API for my website but am unsure if I should make it a REST or SOAP based API and what kinds of features to implement in it any suggestions would be great.
======
pierrefar
Please don't do SOAP. Please. It's painful to use as a developer. REST and
REST-like services are much easier to build for, not to mention debug and
test.

Think about the output your API will produce. JSON and/or an XML flavor? What
about JSONP support?

And do you want users to identify themselves? How? An API key is the usual
way, but Digg has a neat alternative (which I'm using for inspiration on a
soon-to-launch API) of each API call providing an app identifier in the form
of a URL of a web page describing the app.

Also, don't forget to version your API so that in the future if you implement
a change that breaks the default or usual behavior, you can have a chance of
maintaining backwards compatibility.

Rate limiting? If you want that, use memcached or Redis or any super-fast in-
memory store.

Finally, log everything on the server.

------
apsurd
REST and JSON hands down. So easy even _I_ can do it. =) XML has been around
but JSON is so much easier and more efficient that I tend to raise an eyebrow
at services insisting I use XML =/

Start with basic GET services. Have users do admin stuff on your website. Then
create embeddable widgets that present how to use your API to GET and display
data from your service. Use javascript to fetch the JSON, and add it nicely to
the DOM.

It's pretty fun actually.

~~~
AmberShah
I like most of this except the not supporting XML thing. Support both or just
XML. There's just too much stuff out there already using XML that any big
project already has the libraries, whereas JSON maybe not. So it's just more
convenient to most people.

------
joshu
Consider your audience. Specifically: The simpler the API, the larger the set
of people that will build on it.

Delicious used simple GETs with a few parameters and you could talk to it with
a shell script.

Unfortunately, that was before the days of OAuth, which you really need to
support these days. If people build apps that interface to your app, you don't
want people typing their passwords in to the other app.

------
tworats
Take a deep look at both Flickr and Twitter's APIs. Follow their model as much
as you can.

Use JSON and as consistent an interface as you can come up with.

Think through how you'd rebuild your website using only your APIs.

<http://apiwiki.twitter.com/>

<http://www.flickr.com/services/api/>

------
metachris
This presentation from Jushua Bloch about "How to Design a Good API & Why it
Matters" is very interesting, informative and and inspiring:

<http://www.infoq.com/presentations/effective-api-design>

------
gspyrou
If you are using ASP.NET you may check the Web Application Toolkit: REST
Services [http://channel9.msdn.com/posts/LostInTangent/Web-
Application...](http://channel9.msdn.com/posts/LostInTangent/Web-Application-
Toolkit-REST-Services/)

