Service/Web API Guidelines

I haven’t really continued my series on programming interfaces. Mea culpa. Once I started the series, life suddenly turned too busy for planning what I write across several long posts.

This article, however, touches on the programming interfaces topic — it’s essentially a short list of things to do and not to do when providing web APIs. Some points apply to non-web APIs in some programming languages as well.

  1. Use a RESTful approach

    Roy Fielding coined the abbreviation REST, which stands for “Representational State Transfer”. There are many points in his paper I’ll touch on in further points, so it’s well worth reading. But the main point behind REST is probably that the server must not maintain session state.

    There are downsides to this constraint, but it buys you vastly better ability to scale your service to multiple machines.

  2. Choose your serialization format with care

    These days, every few months a new “webby” data serialization format is born, and each is touted as the salvation of the web.

    • SOAP, the allegedly Simple Object Access Protocol, quickly becomes unusable. For one thing, SOAP requests are rarely RESTful — they can be, but that’s not how SOAP is intended to work. For another, SOAP builds on extensibility, to the point where two SOAP implementations don’t necessarily know how to talk to each other any longer. That’s not a good thing to deal with if you don’t control all clients of your service.
    • XML-RPC is something of a counter-revolution to SOAP. It’s an XML-based format for representing method calls and return values, but it’s intentionally simplified to only allow a few basic data types.

      The perceived downside of this is that it forces developers to manually determine how to break down complex data into sets of values of basic types, rather than planning for tools to take over that onerous task.

      It’s not immediately apparent to everyone, but that proves to be XML-RPC’s major strength, because the burdensome part of this task isn’t so much writing the appropriate code, it’s using your brain — and if you do that anyway, you might as well write down specifications for how to (de-)serialize your complex data, and save yourself and everyone else a lot of hassle in the long run.

      Specs and documentation are good.

    • The more recent JSON reads a lot like XML-RPC without XML. The specs support roughly the same basic data types as XML-RPC, and similarly expect the developer to spec what they’re doing before implementing it.

      The first major difference between JSON and XML-RPC are that JSON is more compact. It eschews XML in favour of a less verbose Javascript-like syntax.

      The second major difference between JSON and XML-RPC is that JSON doesn’t use XML. That means that more things need to be specified by the developers — such as a return value’s character encoding.

      The third major difference between JSON and XML-RPC is that JSON does not define a date data type. While that’s annoying at first, all it means is that developers have to spec that little bit more. Make all date values UTC timestamps in seconds since 1970, or use a different standard.

    While it essentially doesn’t matter what format you use, use one that suits your target clients well. Simplicity usually comes at the price of speccing more, but for the most part that turns out to be A Good Thing (TM). Just don’t fall into the trap of assuming that a technology can take away the pain of switching on your gray matter.