REST APIs, their types, and their value chain

First things first, an Application Programming Interface (API) is a user interface to data and systems that is consumed by applications rather than humans. Think of it as an interface through which computers, programs, frameworks can interact with each other via a well defined contact between the consumer and the API provider. An adjacent concept is that of remote procedure calls (RPCs), which can be used by clients (analog of consumers) to invoke procedures or functions from a remote server (analog of API provider) as if it were a local function. Putting these two concepts together allows us to define REST APIs as being an RPC mechanism that follows the Representational State Transfer (REST) design principles. This is a very convoluted way of saying that we represent real life objects or resources through their attributes, which are managed via some persistant storage, i.e., a database.

Why REST?

Probably the most important motivation for adopting a RESTful approach is that it establishes common design principles that all REST APIs must follow, which means that a developer does not have to come up with everything from scratch, they can simply adopt these principles and focus more on the business logic for their software. On a similar vein, these principles/guidelines allows REST APIs to remain flexible and means that they are not tied to any specific data format, although JSON (JavaScript Object Notation) is a common choice, mainly due to being natively supported by web platforms and being easily readable by humans.

Types of API

Keep in mind that an API provider is an organisation or individual that exposes APIs of some sort and that API consumers are entities or users that will use these APIs. However, not all consumers are the same. Broadly speaking we can put consumers into one of three categories:

• Private or internal consumers - part of the organisation that is acting as an API provider;
• Public or external consumer - consumers outside of the API provider’s organisation;
• Partner API consumer - consumers whose identity is known to the API provider and whose organisation has business ties to the API provider’s organisation. In other words, these are trusted consumers.

Conversely, we can define a similar set of types of APIs, that follow analogous definitions:

• Private or internal
• Public or external
• Partner

One very important thing is that these sets do not refer to how the APIs are implemented, they refer mostly to how these are managed. In essence, what API capabilities are available to each type of consumer is purely a business decision, but usually (very strong emphasis on the “usually” part), private consumers have access to the most features, followed by partner consumers and, lasty, public consumers only have the smallest feature set available.

While these sets do not refer to how the APIs are implemented, they do have implementation level consequences related to how secure the APIs are, access request, what documentation is available, and what SLA exists between the consumers and API providers. How these things are implemented is, fundamentally, a business decision and depends heavily on the software’s domain and what type of user is being targetted.

API Value Chain

An API makes the asset of value easily accessible within and outside the bounds of the organisation. Business wise, this has the direct benefit of creating a new revenue stream via exposing the API. Indirectly, it also benefits the business side of life by, for example, empowering the partner ecosystem or increasing brand recognition and awareness.

The end consumers of the asset can be categorized into two types:

• Individual users - public domain apps, browsers, app stores;
• Enterprise users - SaaS solutions, packaged solutions, home grown applications.

Keep in mind that applications are just a way of delivering the value-added asset to the end consumers. Along the API value chain, we have the following interveners:

• Asset - the asset itself;
• API developer - the builder of the API that needs to understand the end costumer’s needs, as well as the needs of the app developers and must support the application development process;
• API - interface via which the asset is exposed;
• App developer - the builder of the end product that needs to understand end customer’s needs, build apps that give value and enrich the asset via customer experience, and should contribute to enhancing the API via feedback.

With this, we can concoct a few high level questions we can ask ourselves prior to building an API:

• What asset of value does your organisation hold that the outside world might not have access to? - This helps establish the “what”;
• Who will get the most benefit from the asset? - From this, we can derive a value proposition for end consumers;
• Is there a business value in making the asset easily accessible? - We’re running a business here, not a charity, although some APIs might be exposed freely without any monetary overhead for the end consumer to increase brand awareness (which typically bolsters other revenue streams);
• Are there partners who will help in delivering the value? - In other words, are there trusted organisations that can build products using your API for you?

Okay, that was a lot of business-y stuff, let’s move on to the good stuff (in the next post of the series, sorry!).