16 August 2012

What makes a good web service API?

On the face of it, the demands of a good web service interface are pretty much the same as for any other API. You just need to make it useful, reliable, easy to use and fast. However, public-facing APIs are forever so it’s vital that you get it right the first time.

Keep it clean and simple

Ideally, you want your API to be at the centre of all manner of orchestrations, integrations and mashups. If you want to attract developers to your API then you should remove as many barriers to use as possible, keep it focused and aim for simplicity.

The more complex your API is, the more likely it is to break. Simplicity isn’t always the answer of course, but it should always be your starting point. You shouldn’t be afraid to leave features out if they add unnecessary weight to your API. You can always add them later on, though be warned that you can never remove things.

You should consider how your API appears from the integrator’s point of view. Your design process should include  writing test API integrations to explore the main use cases before your users do.  It can be easy to over-elaborate your methods and include things that integrators do not really need to see. An API should be about the data and operations that you’re exposing, not your internal organization or application design.

Make it easy to use…

Ideally, an API should be clear enough to use without documentation. Any developer who is assessing your API will usually try to jump straight in and make it work. They will want something that they can get up and running with quickly without having to read a manual. If your API is a byzantine mess of complex data types then you are likely to lose potential customers who will give you a pass in favor of something more accessible.

The naming of your API methods and data should be pretty self-explanatory for your users. Naming is part of your documentation so should be meaningful and consistent. As a general rule of thumb, if you’re finding your API methods and data hard to name then you may want to reconsider your design.

…and hard to misuse

One of the benefits of an API is that encourages the spread of your functionality and data to areas that you wouldn’t normally reach. You may find people are using your API in ways that are hard to predict, sometimes in novel ways that you wouldn’t have expected. This is a good thing as people are extending the possibilities of your applications, but you should make sure that you’re comfortable with this. You shouldn’t expose anything unless you really want people to use it freely.

Ensure backwards compatibility

No matter how carefully you design your API you will want to evolve it over time. A few years of real-world use will reveal some mistakes, the use cases will change or you’ll develop ideas for new features.

This can create difficulties when you have a large body of customers who have already integrated with your end-points. They will expect your services to be completely immutable. SOAP-based services can be particularly brittle as most integrators use proxy-generation tools that throw exceptions if they encounter changes in the original contract.

Not only do breaking changes annoy integrators, but they are likely to trigger a re-assessment of whether they should be using your product or jump ship to a competitor. They are best avoided.

Explicit versioning of services can help manage breaking changes but once a service goes live then you are expected to maintain it perpetually. A more flexible API design can help to avoid breaking changes, but only up to a point as over- abstracting your data structures in the name of flexibility can undermine the usability of your whole API.

Give people options

You shouldn’t make assumptions about how developers will be accessing your API. They may prefer to parse responses via XML or JSON or even work with WSDL files and have proxies created by a code generator – a common way of working in .Net. If a developer can’t use their preferred tool-set to work with your API then they are more likely to look elsewhere. Providing a number of different ways to interact with your API helps to make it more language-agnostic and accessible.

Use the appropriate standards

You should always stick to standards where they exist. It will give integrators more confidence in your API as well as making it easier for them to integrate with it. That said, you shouldn’t drive yourself mad with standards. There does come a point where the slavish devotion to standards can be counter-productive so they should only be followed so long as they support the creation of a clear and accessible API.

Provide documentation

If you want to encourage a large eco-system of integrators then you need to provide the resources they need to get up and running quickly. There needs to be sample code in a number of different languages accompanied by clear explanations of all your methods and data. Ideally, an integrator should be able to start using the basics of your API through a quick bit of cutting and pasting.

Documentation has to be kept up-to-date, both in terms of the method descriptions and languages used in integration samples. This helps to imply that your API is being nurtured and supported. There’s nothing more likely to undermine confidence than inaccurate documentation or code samples that were clearly produced by an ancient version of a development tool.

Don’t skimp on quality assurance

Above all, an API has to work. This applies to all software, but it’s particularly important for a hosted service that other applications will become dependent on. You should also ensure that you test for scalability and develop a good idea of what it will take to grow your service capacity. It is so much harder to performance test after your code has gone live.

Tell people that it’s there (and thank them for coming)

You should create a clear path for developers to find out about your API. They should be able to start using it without having to call Customer Services or wait for somebody from Operations to enable an account. Allow self-service provisioning and free trials. Publicise your API on sites such as ProgrammableWeb. Try to build a community of integrators both online and face-to-face through events and meet-ups.

Above all, there is an important customer service aspect to running a good web service API and developers will want to feel that you care about them. If you look at the commercial APIs that have flourished in recent years they tend to have several things in common, i.e. well-documented APIs with active developer communities, responsive staff and genuinely useful documentation and code resources.

Filed under API design, Architecture, Design patterns, Strategy, Web accessibility, Web services.