API Strategy/Principles — Guide to API economy

API first is the common term used these days. APIs can provide a wide variety of business benefits. They can enable a company to become more efficient in delivering new products and services. APIs make integration with customers, partners, and suppliers flexible and quick.

APIs help organizations adapt to new technology and foster agile development. There is no reason for the business to adopt APIs' first principle, right? Well not really.

All great tools come with their own manuals, and API is no different. Without a proper API strategy, you might end up creating a mess. You need to plan your API strategy which can help to maximize benefits while minimizing risks.

API is not a new technology; they’ve actually been around for a long time. API became the hype only recently, by recent I mean 4–5 years. ( Yes, I am a bit old :))

Why we are talking about API now? Because now the world is connected and APIs are the connection mechanism.

API made integrations easier. API is a code which is pre-written to enable interoperability between two systems. While using APIs, no one has to understand the functioning of the other system. APIs allow anyone to access those systems with only working knowledge of the API itself.

This is different from the old integration process, wherein individual adaptors were written for each connecting system. Think of a scenario wherein a system connects with 100 other systems, we need to write 100 adaptors (fixed cost) and then maintained those 100 integration points.

Yes, it is true, if used properly will provide you direct cost saving.

The agility we see today in every business vertical is made possible primarily because of the API economy. Companies can extend their borders to new geographies, suppliers, devices, or customers far faster than they could in the past.

It is important to define policies, standards, and governance upfront to ensure that APIs are used in the most cost-effective way.

The high-level API policies we use are those which are defined by Jeff at Amazon. His mandate to developers at Amazon was simple and straight forward.

• All teams will henceforth expose their data and functionality through service interfaces.
• Teams must communicate with each other through these interfaces.
• There will be no other form of inter-process communication allowed: no direct linking, no direct reads of another team’s data store, no shared-memory model, no back-doors whatsoever. The only communication allowed is via service interface calls over the network.
• It doesn’t matter what technology they use.
• All service interfaces, without exception, must be designed from the ground up to be externalizable. That is to say, the team must plan and design to be able to expose the interface to developers in the outside world. No exceptions.

The mandate closed with:

Anyone who doesn’t do this will be fired. Thank you; have a nice day!

Think about what Bezos was asking! Every team within Amazon had to interact using web services. Jeff asked teams to decouple, define what resources they had, and make them available through an API.

There is no direct connection, all departments systems only connect with each other via APIs.

Eventually, this turned out to be the key to Amazon’s success.

Key aspects to add to your API strategy ;

Discoverability of an API, if a developer fails to find already written API then it will lead to a situation wherein every developer writes a new API for the same function. How to make API discoverable.

Consistency: If one common function is built in a particular way then all to be built in the same manner.

Security and Access: Standard security and access controls for each and every API. Todays, internal system API can be used by under department or become externally published. Access and control ensure sensitive data is not exposed.

Naming Convention; use nouns and entities for API names, don't use very as API name. For example, API to access all user should be;

/users

and not

/getallusers.

“The system should speak the users’ language, with words, phrases and concepts familiar to the user, rather than system-oriented terms. Follow real-world conventions, making information appear in a natural and logical order.” — Nielsen

Use Standard HTTP codes. Don’t limit yourself with just 200 or 500. HTTP has plenty of HTTP Codes. The response status code provides a good, basic level of system status information. For example, the 2xx series informs a caller that things went well, while the 4xx and 5xx series indicates some type of failure.

• 200 OK — Success.
• 201 CREATED — Response for a post request.
• 202 ACCEPTED — Ack for the response to the server.
• 401 UNAUTHORIZED / 403 FORBIDDEN — When security check fails.
• 500 INTERNAL SERVER ERROR — Most commonly used for error.
• 502 BAD GATEWAY — This can be used if the server received an invalid response from the upstream server.

APIs are a great tool for integration and communication but without a properly defined strategy, you will end up doing more harm to your product/organization.

Feel free to reach out to me for a customer API strategy for your product.