You Need a REAL API Interface

I have to admit, I’m having a great time at API World. From hearing different talks and ideas, to the launch of Swagger Hub, to seeing all of the new technology surrounding APIs and integration.

But as everyone rushes towards building APIs, and looks for shortcuts, it’s also important to remember that there are no such things as shortcuts in building quality software that lasts. And in the end, shortcuts often times cost far more in the long-run than it would to do it right in the first place.

More than ever I’m seeing automated API generators that plug directly into backend systems, letting you create “RESTful” APIs on the fly (or literally creating your API from your database schema). This is a GREAT way to have immediate access to systems such as databases without having to write any code – but there’s a HUGE tradeoff, and in essence the API you are building around these systems defies really every reason to have an API in the first place.

The Interface

Obscures & Protects Your Architecture

For starters, the first thing you lose is the power of the interface. Sure, you will have a JSON representation of your data, BUT this is a representation that is not only tightly coupled to your database schema, but gives your schema away altogether. A good API interface should HIDE the backend technologies from the user, preventing them from knowing how your architecture works. It should also simplify the process, giving the only the information they need in a way that is easily digested (instead of having to figure out how your relational database keys relate to each other and now relate to each other in API calls).

Allows for Independent Evolution

One of the key constraints in REST is client/ server, meaning that each can evolve separately of the other. However, these automatic API generators actually again tightly couple the client to the system architecture. Without any way of versioning, any backend change will automatically break the client. Doing something as simple as fixing a typo in the database field could have detrimental effects for your users.

As I share in my book, Undisturbed REST, you should not only be able to change small things in your architecture, but actually rewrite or replace your architecture altogether without impacting your users. A true independent interface allows you to do just that.

Allows for Validation of Data

Another crucial piece a true interface offers is data validation. Because the API is the middle-man between the client and your architecture, it is able to instruct the client on how to send the data and ensure data integrity – BEFORE the data hits your architecture. With these new systems, outside of some scripting capabilities, data is immediately stored in your backend – for good or for bad. That means you’re opening your system up to all sorts of incorrect, partial, or malformed data.

REST Gives You Control

Not only are you giving the users all of your fields and data, but you have essentially given up control over HOW that data is presented to your users. There are some scripting mechanisms that some of these solutions are offering, but you still lose control over whether or not they are allowed to access certain resources or methods.

Perhaps you only want users to be able to retrieve data, but never had any intention of giving them control in regards to whether to create, edit, or delete your data… unfortunately with some of these solutions you get little to no say.

A HUGE part of any API is governance, or what users will have access to, and how you will protect critical (or private) data, as well as your system architecture.

In Reality

I’m not a fan of these backend automated API generators because what you are REALLY doing is giving users direct access to your database or other backend systems through a pseudo-proxy. Honestly, you’re probably better off creating a database user and setting the specific permissions you want for that user in this case. Yeah – I said it, just give them access to your database – because that’s essentially what you are already doing.

Do It Right

I’m not saying these tools have no purpose, or don’t provide some nice abstractions to keep your users out of the database or from having to write sometimes problematic SQL… but if you’re trying to expose and control your data – there’s a better way to do it. The right way.

It’s not as fast, and it’s certainly not as cheap – but by taking the time to create a REAL abstraction and interface for your system, and build an API that your users can actually use (without giving DevOps a heart attack) you can ensure data integrity, system security, tooling longevity, system and architectural flexibility, and make up for the extra costs in the long-term (or with just one “I accidentally deleted critical records using the pseudo-API” ticket).

So to summarize – if you value your data or architecture, take time to invest into your API instead of trying to create cheap solutions on the fly. Take time to spec it out and understand what it is you actually need, and then put the proper layers of protection in place to ensure that your API actually acts as a solution and doesn’t become part of the problem.