Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I'm currently building a web API for popular piece of forum software (XenForo). What kind of things do developers find important in a web API? Are there certain architectures (REST, SOAP, etc.) that are much better than just doing my own thing?

The API I have the most experience with is MediaWiki's API, but that doesn't seem to follow any sort of standard. What should I be planning to include (e.g. output formats, OAuth) and what are some good examples to follow?

share|improve this question

migrated from stackoverflow.com May 24 '11 at 12:23

This question came from our site for professional and enthusiast programmers.

IMHO skip soap. A JSON based REST API is all most developers need. –  scunliffe May 24 '11 at 12:01
... to a point. SOAP is really useful for software that needs APIs and access from 'workflow engines'; mostly for non-interactive types of functionality. For interface/web type integrations, REST is the way to go. –  Chad Thompson May 24 '11 at 13:42
Documentation. –  Josh K May 24 '11 at 14:47
Keep it simple Make sure your object model that you use in your service may it be JSON or XML is as simple and clear as possible. –  Newtopian May 24 '11 at 23:48

8 Answers 8

After you document your API, but before you start coding your web service(s), try to write some code that uses the API.

If you succeed easily, then your API is usable. If not, you'll know where to make changes.

Include the code you wrote as part of the API documentation.

share|improve this answer
This attitude taken to the extreme is Test Driven Development. –  user1249 May 24 '11 at 15:16
@Thorbjørn Ravn Andersen: More like Test Driven Design. :-) –  Gilbert Le Blanc May 24 '11 at 15:18
This is good advice, and in fact, I like to try to start writing code against the API before I have even decided anything about it. Whenever I wish my API had a certain feature, I just pretend its there and write the code to use it. Once I have some code like this, I'll implement the API. This keeps me from writing an easy-to-implement but hard-to-use API. –  PeterAllenWebb May 24 '11 at 15:50
I've been the guy writing the first client against a number of APIs. It hurts when the devs never tried to talk to it . . . –  Wyatt Barnett May 25 '11 at 1:31
  • Good documentation
  • Access to a sandbox/test realm
  • Support for common access methods and result formats
  • Example API libraries for various platforms
share|improve this answer
  • Consistent naming of function and parameters;
  • Stability and backwards compatibility;
  • Up to date documentation, covering all of the functions;
  • Lot of real life examples with sample code;


  • RESTful API
  • JSON, preferably with with JSONP support
  • standard authorization methods (OAuth, OpenID, Facebook Connect).
share|improve this answer

There's no universal answer, it depends on what you have, what you want to do and what who will consume it can do.

Usually, stick with JSON/XML for the payload and existing standards where available (e.g. OAuth, OpenID, ecc).

And most important be consistent, keep it simple and document how things works.

As a programmer, it's all what I ask for.

share|improve this answer
+1 for "standards", even if not official standards. I think developers look for familiarity, so they are more likely to use it if they don't have to figure out how to use it because it looks similar to others they've used. –  ale May 24 '11 at 12:36

If you were building the forum from scratch, I'd say build everything as a JSON api, follow an HMVC approach and when your app is done decide which parts of the api to make public.

For an existing app like your forum, it would be extremely nice if you provide RSS for everything public:

  • Discussions / Posts
  • Categories / Tags
  • User profiles
  • etc

And build a sensible mechanism for building custom rss feeds:

If http:/myForum/category/Cat1 is the url for category Cat1 then:

  1. http:/myForum/category/Cat1.rss
  2. http:/myForum/rss/category/Cat1

are possible candidates for the category's feed. Pick one and stick with it (or pick something else but do stick with it). Let's say you picked the first one, do some extra magic and build stuff like:


So if you do follow my advice and go with rss for everything public, that leaves us with everything that needs authentication. So the obvious first thing to build in your api is OAuth. Other sensible stuff for a forum api:

  1. Let me edit my profile
  2. Let me post an article / comment

For the more high level stuff:

  1. Give us some way to decide on what version of your api we prefer, especially if you're expecting to have multiple versions in the wild
  2. Be fanatically consistent when naming things
  3. Working real life examples are more important than documentation
  4. If there is no documentation noone will bother with the real life examples.
  5. APIs must be extremely fast. Cache / compress / do whatever possible so it takes me less than 15 seconds to post via my extremely slow GPRS
share|improve this answer
btw the second / in http is ommited to not be treated as a real link... (if there's a link, people will click on it). –  Yannis May 24 '11 at 15:02

Well, the best you can do is develop an SDK for a popular language (say JavaScript), that presents a local abstraction layer atop the API, to see how hard using your API is.

When I use an API, I want ít to be straight forward. I want all the technical details to be transparent. It should be as simple as calling a function that is evaluated right on the client.

To achieve this, the most simple way is to automate as much as you can.
A possibility is to use WSDL to describe your API and use appropriate tools to generate the skeleton code for your server side as well as the SDKs for the various client languages.
Not that I like WSDL, but there's a number of code generators and frameworks that handle it well.

You want you API to be clear, consistent and based on popular technologies. No fancy stuff. No jury rigged homebrew. Don't reinvent the wheel. Focus on building a good vehicle instead ;)

share|improve this answer

I agree with the other posters who suggested to focus on standards.

However, I would go one step further: just use AtomPub. This is exactly what it was designed for.

It came out of the blogging community, after all, so reading and publishing articles is squarely within its domain.

share|improve this answer

Everithing but the kitchen sink. But of course you want to provide some extensibility to the API so we can plugin the kitchen sink if needed

share|improve this answer

Your Answer


By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.