API First Design & Architecture

Fri, Jun 12, 2015

Why APIs?

Modern scalable architecture is designed for the cloud and multiple customer channels that you may not of thought of yet. Abstracting your functions as a set of micro-services defines an ecosystem where an applications are created as an aggregation of calls to autonomous services and where loose coupling is king. Micro-services promote scalable agile solutions and allow true flexibility to a exploit multiple dimensions when provisioning compute capability. With a monolithic architecture, agility and scalability options are greatly restricted.

APIs and micro-services are a departure from the previous generation of SOA solutions where middleware was employed with mapping to and from canonical models was the norm. This may have been ok when system component provided only scant integration capability but this is no longer the case. Commercial packages now ship with comprehensive APIs as vendors realise that flexibility in channel support is now an out of the box expectation.

But what APIs should be exposed?

There is no secret that poorly designed APIs will promote a difficult to maintain ecosystem where a proliferation of similar services can quickly create a maintenance nightmare and promote higher cost of maintenance. I suggest that APIs be grouped according to business capability, be predominately stateless and exploit elastic IaaS and container capability. A good API will satisfy a customer or staff interaction and will not simply expose functions included in a backend ERP or system.

Some other tips include:

Understand the actors in the business operating model - A good digital business strategy will have identified personas and interaction hot points.
Clearly define the Business Capabilities in a model - Look for industry reference models that tell you what capabilities that you should aspire to. Socialise the model and solicit business feedback to refine the model and therefore the services that you will need.

Agree on the business terms and definitions as this is the language of your flows - In a loose coupled world with key value pair style interfaces it is important that the meaning of keys is agreed.
Apply a rule of measure to your existing services? Just because they exist is not a good enough reason to reuse them. Are they fit for purpose?
Track your APIs along with the consuming applications. This will help maintaining the ecosystem and ensuring that change impacts are properly assessed with each interface change.

What is the logical layering?

In general, an API ecosystem can consist of many layers depending on the complexity of the environment. The key tip here is to not over do it. Three is generally enough:

Channel Service Layer - This layer is generally used to create composite services that simplify the interaction between client applications and the core business services. The best example of this in a commercial setting is at Netflix where the number devices consuming streams is ever changing. Native mobile apps and we based clients all share business services via specialised channel adapter services.
Business Service Layer - This layer houses all of the scenario based APIs that expose business capability. They can also be composites making use of enterprise services exposing entities and functions in core and supporting systems.
Enterprise Services Layer - This layer includes the utility services such as entity storage, document generation back office shared capability. At this layer, heavier weight services are often translated in the light weight services that can easily be consumed in the higher layers.

And do you still need middleware?

The answer to this will vary based on the application ecosystem. For Enterprise Application Integration such as calls to services requiring guaranteed delivery the answer is yes. But there are other ways to this with many vendors offering overlay models in the form of API gateways that allow layered application of logging, security and a level of syntactical schema enforcement.