Four core values for API development

Like others, I've become a big believer in APIs in the last few years. API architectures are fairly easy to discuss technically, but harder to explain to people who don't have a technical background. I've also noticed that when people write about APIs, they tend to focus on implementation details or management issues. Explaining why this or that technology is good for implementing APIs, or why you should definitely invest in API management.

Personally I am not that worried about either of those two things. To me, the big thing about APIs is the contract, and the promise that it represents. Looking at the API from the outside you have no need to know how it is implemented, or what the management process looks like. Those things matter as well, but since they happen behind the scenes you can change them with no noticeable effect on the outside. This is one of the reasons why I tend to focus on the big picture when talking about APIs.

Since I meet with clients with different backgrounds every week, I've tried to come up with straightforward ways to describe how digital service platforms based on APIs should be brought to life, and how the platform itself delivers real business value. In this quest of trying to distill my message into itse purest form, I have had to think a lot about what I think are the most important things in succeeding with API development. Over time these have been filtered down into four core values. Even if you do no other planning, staying true to these four things will keep your platform heading in the right direction.

If you are a startup working on greenfield cloud apps these will seem obvious to you. But if you have a large existing base of systems and services you are looking to transform, these ideas may give you some clarity.

My four core values for API platforms:

1.OPEN

By openness I actually mean two things. You should implement your APIs through open standards (almost always HTTP(S) and JSON these days). And they should be open to the internet. If you feel like you need to buy tools or products to get started with APIs, you are probably doing it wrong.

Opening up your services may not seem like a big thing, but it is a massive bottleneck in getting other organisations to want to use your platform. If you need to start thinking about opening up firewalls when your client or partner comes up with a new idea they would be willing to try, you have already lost.

The goal is to have a very low barrier of entry for integrating new channels and services with your APIs. The three weeks it takes your firewall guys just to get the ports open may be the entire duration for the implementation of a new concept. There will be cases where the business benefits are so obvious that you can live with that three weeks. But I guarantee there is also a long tail of less obvious cases, that have never been tried due to being bottlenecked by the IT department.

Being open also doesn't mean everyone out there has to be able to access all of your services. You can secure services that you expect to be used by other servers with API keys. Some of my clients even use API keys to validate client applications, simply to prevent random internet wide scans ever going beyond the edge of the network.

2. SIMPLE

This one is something you need to constantly work at. Your APIs should hide all the horrors of your internal systems and processes. And I mean all of them. The fact that you haven't been able to consolidate your ERPs should never be visible from the outside.

Ideally your services must be intuitive enough to be used by someone outside of your company, without active participation by you. Developers are lazy, so you need to keep chipping away at this for as long as you are investing in your API layer. Again, this is about lowering barriers and making sure the cost of entry to your platform is as low as possible. If you make your APIs a pleasure to use, you will see wider adoption of them in the long run.

Don't take things for granted even if you see some initial success. Be ready to make changes to your interfaces where necessary. Don't be afraid of making services that have become too verbose bigger, or of splitting others that have become too big into smaller pieces. The only constant is change. Build a development and deployment model than embraces it.

3. FAST

By fast I mean your APIs must ALWAYS respond in milliseconds, never in seconds. At the other end of your API there may be an actual human being, sitting on the end of a user interface, waiting for a response. Since we also know that good user experience is a sum of good usability and speed, it becomes obvious that your APIs have to be fast. Repeat after me: THEY HAVE TO BE FAST

If the backend services your APIs use are slow, you have to work around the problem. Build caches and online databases, turn synchronous calls in asynchronous ones, do anything and everything in your power to make sure your APIs are always fast. Not "fast enough", actually FAST.

4. SECURE

This one is kind of obvious, but I always include it. You really can't talk enough about security. Even though your APIs are open, simple and fast, they must also always be secure. Every rule that ever applied to developing secure web sites also applies here. Your API services are now where your website used to be, so act accordingly. Always use HTTPS, embrace token based authentication, use API keys and generally figure out a way of working that takes security into consideration from day 1. Be prepared to respond to security issues rapidly.

There be dragons out there.

If you build it, they will come

These are my four core values for developing APIs. Implementation wise I think you can succeed with almost any modern technology. Some of my clients invest in API management early. Others just start implementing, and worry about management once they have a few services in production. Some use Node.js, others use Java or PHP.

You can succeed in many ways, but I believe you should always have a set of core values that act as your compass - helping you head in the right direction even when it is not absolutely clear what the right thing to do is.