Reasons for a Service API

Today at work I ran into an unfortunately not-too-uncommon problem with another software engineer. The really unfortunate bit is that I found myself on one side of an argument when I’m quite often (more often really) on the other side of it. That’s because regardless of one might say about this class of issues, there’s hardly ever a solution that fits all situations.

So here’s the scenario: one of you is developing a service of some sorts, the other is developing a consumer of that service. In this particular instance, the service is used by several consumers with somewhat different needs.

The consumer I was developing1 has fairly specific requirements on the API the service is providing, which the API doesn’t fulfil. Other consumers found it simple enough to work around this lacking feature.

So what are you to do?

The consumer developer’s view

If you’re consuming an API of sorts, there’s usually a reason for it. There’s roughly two distinct scenarios; in one you require the service to provide yet another service, and in the other you present a user interface to the service.

Let’s start with the second case first, because it’s somewhat simpler. You’re developing user-facing software, so your decisions are very closely related to your user’s needs. Whether or not, for example, you provide an interesting piece of information on the view the user is most likely to use most often, or a click or two away is directly dependent on how much information you need to display in total, what the screen estate is like, how vital the information is to the user, and so forth.

Now to carry this example further2, if you decide to display this piece of information on the view the user is most likely to use most often, then it makes sense to retrieve this piece of information lumped together with the rest of the information you intend to display along it.

Why? Because as a rule of thumb, each call to the API results in more or less noticeable delays for the user. In a world where user of web sites decide in less than a second whether or not they’ll continue exploring the site, it’s crucial to minimize these delays.

So if the API developer then decides that — for good reasons, I’m not assuming the API developer is stupid until proven otherwise — the information you need in one lump must be retrieved via separate API calls, as a user interface developer, that’s frustrating.

The first above mentioned consumer case is frustrating for related reasons, easier to explain now that this one is (hopefully) clear. If you provide a service/API to someone else, and rely on a service/API yourself, any delay and inconvenience introduced by how you’re forced to use the API multiplies before it reaches the end user. In other words, if the service I’m providing is slow because a service I’m relying on is slow, users of my service will be frustrated with my work. They don’t care how I do things in the same way that I don’t care about the other service’s inner workings, I’m just interested in how to conveniently use it.

That’s the consumer-centric view. And given that it’s all for the goal of providing the best possible user experience to the end-user, this view has an incredibly appealling logic to it.

  1. I usually develop libraries or servers, so service providers rather than consumers — that’s why I’m usually on the other side of the discussion. []
  2. This isn’t what the issue at work was about, but is illustrative of this class of problems []