un|we|sen

3. Be consistent

   Many APIs, on the web or not, provide access to data — as opposed to providing control over something. Say your data item Foo is a set of three basic values. Follow a few simple rules for the sake of consistency:

   • Choose consistent names for the values in the set, if your output format supports naming set members. Names are consistent if they’re always spelt exactly the same if they name the same thing, i.e. bar, Bar and BAR are not consistent.
   • Order the values in a set in the same way, i.e. if bar follows baz in one situation, that should be the case for all other situations as well. If the order of values has a specific meaning, specify which meaning it has in each case.

   Note that this in no way means clients should rely on consistent naming and ordering, unless they absolutely have to. But producing consistent ordering and naming in server responses means clients that have weird restrictions stand a chance of talking to your service.

   The most important point about consistency, though, concerns lists of data items. It is quite often the case that your API allows access to lists of data and/or individual data. If you have two API calls that return lists of Foo, say one for the most recently added Foo, and another for the most recently used Foo, then unless there is a very specific reason to break this rule, return these lists in the same format.

   It sounds like such an obvious thing to state as a rule, but you’d be surprised by how often I’ve seen this particular rule broken. If there’s a reason to return the number of results in one list, return it in the other as well. If one must be an “array”-style list, return the other as an “array”-style list. If one must be a key/value-style list, return the all as key/value lists.

4. Be clear about the scope of values

   This is really another sub-point to the previous point, but taken out for special emphasis.

   It’s quite common that, for example, when returning a list of Foo, you’re interested in a smaller number of Foo’s member values than when returning a single Foo.

   Let’s say your Foo are users of your website — if you want to list users, you’ll be mostly interested in their name and a few other items, but the full user profile usually contains a lot more data than you need per list.

   It’s deceptively easy to define a set of, say, three values as the list representation of Foo, and the set of all values as the non-list representation of Foo. And speccing these different representations properly is already a lot better than most people do.

   Even better would be to parametrize each API call, list or non-list, with a parameter that specifies what set of values for Foo you’re interested in.

   There’s a simple reason behind this, that’s easy to ignore when starting out on developing an API. In most cases on the internet, multiple requests to a service prove to introduce more latency than a single request with a larger amount of response data. There’s a balance to this, of course, but as a rule of thumb that works surprisingly well — especially because most people seem to have a tendency to optimize in the opposite direction¹.

1. It helps if you keep reminding yourself that the internet is a packet switching network. That is, up to a certain amount of data transferred, the latency introduced at each switch in the network is O(N), where the N depends on the switch’s load. If you exceed that amount of data, the latency becomes O(N*M), where M is the amount of packets you’re sending. Even if you’re counting bytes in your protocol, it simply does not matter in practice how large your packets are, as long as M remains low (ideally 1). [↩]

You can follow any responses to this entry through the RSS 2.0 feed. Both comments and pings are currently closed.