What do programmers want in a web API?

Question

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?

Answer 1

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

Answer 2

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.

Answer 3

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 ;)

Answer 4

• Good documentation
• Access to a sandbox/test realm
• Support for common access methods and result formats
• Example API libraries for various platforms

Answer 5

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:

http:/myForum/category/Cat1+Cat2+Cat3.rss

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

Answer 6

• 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;

Technologies:

• RESTful API
• JSON, preferably with with JSONP support
• standard authorization methods (OAuth, OpenID, Facebook Connect).

Answer 7

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.

Answer 8

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.