A playbook for API-first transformation at scale- Delivery Infrastructure Platform Part 1

In the previous post and the post before that we talked in detail about the API product development lifecycle and the different phases-Align->Design->Develop->Release. In this post, we’ll cover the Delivery Infrastructure Platform (There are many other names, but we’ll stick with this name). Delivery Infrastructure Platform is one of the key building blocks of API-first transformation. The scope of Delivery Infrastructure Platform extends to lot of things in an organization- From providing a compute infrastructure for both operational and analytical needs, to a modern CI/CD pipeline, to a set of tools/services for reliable communications, to a modern observability system, to providing tools/processes for building secure services, to effectively perform identity and access management, to enable data privacy via a set of self-service tools, APIs, services and support, and so on. This post would only discuss the items of the Delivery Infrastructure Platform that are core to the context of API and service design and skip all other concerns (such as details about compute infrastructure, CI/CD pipeline, IAM infrastructure and observability infrastructure).

So, what does Delivery Infrastructure Platform contain and how to build one?

Remember from the last three posts, when we talk about a service, we talk about it as the physical artifact or the implementation around a business capability and an API as logical artifact that exposes a business capability’s functions via a well-defined and easy to understand set of operations. These business operations are documented in the form of an API contract by using an Interface Definition Language (IDL) and consumers (or clients) consume the business capability by making API calls to a service implementation. When we think of a client consuming a business capability via the APIs exposed by the service, there are several things that come to mind,

1. Transport-The underlying transport protocol that clients use to make API calls, for example, HTTP or FTP.
2. API Protocol-The API protocol that a service uses to expose its operations (e.g., REST or any of the RPC style protocols such as GraphQL and gRPC).
3. Service runtimes and libraries- The language specific service runtimes and libraries that service developers use to develop services.
4. Reliability- All API calls MUST be reliable-no more, no less. Google puts “Reliability of an Application” as following, “Reliability is the most important feature of any application, because if the application is not reliable, users will eventually leave, and the other features won’t matter.”. Reliability of API calls is a default client expectation, regardless of the industry segment you serve. Reliability is a nonnegotiable feature if you are in the financial industry and dealing with money. Traditional API calls are served over HTTP and over the network. Further, a service call (of higher order value and serving end-users) may result in a chain of calls to other services (services of lower order value of foundation platform services) over the network. While the micro-services architecture provides many benefits, it also presents many challenges. The local in-process calls of a monolith are suddenly replaced with network calls between many micro-services. Networks are unreliable-latency and transient failures are always a concern, resiliency (the ability of a system to react to failures and gracefully recovering from it) is an absolute need. Resilient communication further requires retrying of failed requests, in turn requiring many calls to be idempotent to ensure a consistent system state. Reliable inter-service communication and reliability of data is a critical concern.
5. Observability-Micro-services talk to each other over the network to serve the end-user calls with each call conforming to predefined SLOs (Service Level Objectives) and generate logs to record the call execution results. Correlation of calls (using Distributed Tracing), monitoring of logs, generating appropriate alerts, and keeping the overall system in good health is also a critical requirement.
6. Security, Identity and Access Management- With the Micro-services architecture, each service is now required to securely handle storing of sensitive data locally (keys, secrets etc.), securely communicate with other services (via TLS) and manage Identity (the principal) & Access (what the principal is authorized to access). Security and IAM are key critical concerns too.
7. Data Privacy- Of late there has been increased regulation from around the world to protect personal data, in the form of government legislations such as CCDA, GDPR etc., and each country is coming up with their own data privacy legislations. Data Privacy should not be an afterthought anymore. Data classification and handling in the infrastructure is a MUST do thing and a first-class infrastructure concern, after all, most APIs would need to deal with a customer’s personal data in some form.

The Delivery Infrastructure Platform enables all the items from 1 through 7, via a set of self-service tools, services, APIs, documentation and support.

(Note: From the previous post, all the above items, 1 through 7 are clearly articulated in the design/architectural standards so a Delivery Infrastructure platform would essentially implement them so product developers can focus on only working on value-adding product features)

To summarize from all posts so far,

1. The Business Capability Model (modeled using Domain-Driven Design Principles) enables organizations to stay business-oriented and customer-focused through clearly defined business capabilities and service boundaries. Clean service boundaries enable teams develop functionally cohesive, loosely coupled, encapsulated and reusable services.
2. The Design/Architectural standards defines guidelines, service design principles and patterns to build robust, reliable, and secure services that expose stable, well-documented and easy to use service contracts (aka APIs) to its customers.
3. The API product development lifecycles defines the service development lifecycle phases (Align->Design->Develop->Release) to build an API product, roles/responsibilities of various stakeholders in the lifecycle phases, the quality criteria (aka maturity criteria and score evaluated by checking the compliance of the API product with the Business Capability Model and Design/Architectural standards), for entry/exit between these lifecycle phases.
4. The Delivery Infrastructure Platform provides a set of self-service tools, services, APIs, documentation, and support that helps end-user facing product developers focus solely on building value adding product features and by leveraging the platform’s tools/services to implement all non-functional concerns and to build robust, reliable, and secure services.

Now before we discuss the tools, services, APIs, libraries that comprise the Delivery Infrastructure Platform, it is important to discuss all its customers and what they expect from the platform. Remember from all posts so far, product thinking is ingrained into everything we do. Delivery Infrastructure Platform is a product for an organization’s internal developers.

Business Owners (Engineering and Product)

Business owners/sponsors are interested in tracking their complete product portfolio (the inventory of their business capabilities, API Products, Data Products (not in scope of this post) and services), quality of each API product and the overall portfolio quality & health( Health of all of its API products, for example, how they are performing, failed client interactions), their usage (by end users), tech debt management (legacy, deprecated API products, client migrations etc.).

Portfolio Manager

The Portfolio Manager is responsible for performing the API product portfolio alignment step of the API PDLC to correctly position the API in the portfolio and to detect any overlaps so she should be able to discover all the business capabilities and the associated API products.

Service producer (aka Engineering Owner or API producer developer)

A service producer would perform API lifecycle management, manage metadata (more on this later in the post), design APIs/services that are design standards compliant, meet all other compliance standards (security/privacy/legal compliance), manage consumers, request/complete reviews, notify consumers, generate functional and non-functional code and so on.

Service Consumer (aka API consumer developer)

A service consumer would like to discover various API products using different dimensions (business domain, capability name, filters), explore API contracts (view request/response schemas, samples, errors etc.), try executing API requests, subscribe/generate API credentials, browse mock endpoints, generate client-side code and so on.

Reviewers (API/Service Designer, Security/Privacy/Compliance Reviewer, Release Readiness Reviewer)- Reviewers in the API product lifecycle are responsible for ensuring compliance to the respective standards laid out in an organization via a combination of automated validations in the CI/CD pipeline and manual review (as appropriate) and complete the maturity assessment for the criteria the reviewer is responsible for.

Automated Bots/Applications

Various Automated Applications bots should be able to query for details about all APIs, Services, Metadata on need to perform a specific task. For example, in your CI/CD pipeline, you can check the maturity/quality score and surface it as a deployment requirement if the API/Service quality doesn’t meet the required score for deployment.

Conclusion

This is the Part1 of the Delivery Infrastructure Platform. In the second part we’ll discuss all the tools that comprise the delivery infrastructure platform.