The 5 Biggest Challenges With APIs

Over the last couple of years, we’ve heard a lot of breathless talk about application programming interfaces (APIs) and how they’re going to change everything. 

APIs exist to solve a fundamental problem: how can a group of people use stuff written by a different group of people, who may have had different ideas and expectations? With a clearly defined API, you can establish a set of rules that outsiders need to follow if they wish to use your code. 

Until relatively recently, this was done in a fairly ad-hoc way. People would go into a dark room with a whiteboard, lock the door, and refuse to leave until they had nailed down and agreed on every aspect of how things would work. This was expensive, time consuming, and relied on weird ad-hoc methods of explaining what the API was.

But now there are technologies like OpenAPI and Swagger, which allow you to define an API in a standard way in considerable detail — enough detail, in fact, to generate the code for it programmatically. 

Surely this is a good thing?

Yes — but there are some issues. 

Let’s look at the five reasons APIs are struggling to live up to their hype and why this may not matter. 

API Challenge #1. It’s very hard to get the abstraction level right

Are we selling rare stamps? Any stamps? Any physical object of value? Any object of value, be it physical or otherwise?  You can easily see how an API for any of these would have to make assumptions to be useful, or run the risk of being so vague as to be meaningless.  People are finding out this is not as easy to do as it looks.

API Challenge #2. Real-world systems have real-world anomalies

The real world imposes its own rules on us. A very simple example: in Ireland, it can be challenging to buy things online from UK-based companies. The rules for this process tend to be arbitrary and can change suddenly. So if you live in Ireland and are using an API to find cheap flights, for example, the API might return entries that are very cheap but also utterly useless because it assumes you have certain travel permits, or are a member of a particular group, or are willing to travel at 0400 on a Wednesday. Attempting to model this stuff leads to the problem above, where a too-precisely-defined interface becomes useless.

API Challenge #3. Existing systems don’t easily fit into the new API definition

Last year’s Mobile World Congress (MWC) was attended by a number of vendors venturing into the API space. One of the biggest issues for large, established vendors is that they already have existing systems, systems that could be really, really hard to fit into the public APIs without significant extra work and loss of functionality. 

API Challenge #4. There are political forces at play with their own agendas

Because of the inertia existing systems create, their owners have powerful incentives to nudge the structure of the API to align with their legacy codebase. This can lead to a ‘camel-is -a-horse designed-by-committee’ situation, where the resulting API is more a reflection of battling political wills than technical common sense.

API Challenge #5. Writing the API doesn’t mean you’ve written the application

This is probably the biggest problem. People are so hung up on perfecting and tweaking the API that they don’t get around to delivering usable code nearly fast enough. Given that the two most important words in software are ‘done’ and ‘finished’,  this is a problem. And while the APIs define contracts for what gets passed back and forth, we generally don’t discuss expected latency or availability.

But: API code generation is a serious time- and resource-saver

But despite all of the above, there are a few undeniable, unarguable facts: APIs will reduce labor, accelerate development, and also potentially make development more reliable. Lots of pointless legwork is going to be replaced with auto-generated code, meaning code that people previously tended to skimp and rush and that had nothing in itself to do with creating business value can now be auto-generated and not take up developer’s time.

When you are looking at the potential to auto-generate 50% of your code, the drawbacks above become instantly ‘okay’ in comparison

How does this all relate to Volt?

Here at Volt we’ve been watching the API ecosystem for a while now. We have two internal projects: the first aims to take published APIs and generate stub Volt code, as well as app server code, to run them. This means you could take a Swagger YAML file and end up with the beginnings of a Volt application.

The second approach is to use Java annotations to expose Volt procedures as APIs. This makes the most sense for new builds or custom applications that aren’t expected to follow a predefined API.

In both cases, we do more than remove the need to write the ‘plumbing’ code API generation normally eliminates; we also write all the necessary app server code. All logic is implemented inside Volt. Because of the way Volt works, this drastically simplifies the error handling you’ll need to implement, as it’s much easier to do if it’s inside the server than on an app server. In practice, we expect to remove the need for half the remaining code.

Contact us to learn more about how Volt will accelerate your API journey.