Elements of an Successful API Strategy

A large number of enterprises still employ large, monolithic applications. Using and maintaining legacy applications impairs business agility due to their long release cycles and high costs to maintain and evolve.

Companies that develop or maintain legacy applications may have strong competencies in their business domains, but lose competitive advantage to nimble entrants that are able to release new product features at higher velocity than the incumbents by developing their products with the microservice architecture style at their core.

Transition Impediments

To maintain competitiveness, legacy-product companies may decide to re-platform their software products on microservices to address the underlying technical debt of monolithic applications. Deeper in the organization, development teams that maintain these applications may view the APIs of the new microservice architecture as being ‘internal’ to the organization, and resist opening them up to their clients.

I’ve observed that organizations start their transition journey towards API organically - deferring to the technical teams the planning and implementation of the change. It starts with a one team pilot, and then it expands to the rest of the teams, which are domain siloed. Such a tactical approach may result in inconsistent API designs and implementations, as API definition files (*.yaml) are limited in scope to only a few end-points, or to the domain at most. Inconsistencies in designs become apparent, when different API definitions have disjoint designs for common objects, such as parties, addresses, or contact information.

In order to avoid the misalignment that results from organic transitions, companies need to update their corporate strategies to include API specific goals.

What does a company need to plan for, and do to be successful when transitioning to API centric architectures?

Assertions

APIs need to be considered a product, and product specific considerations need to be addressed upfront. From a marketing perspective, it is important to recognize is that APIs are products used by developers; they are not an end-user products.

APIs products need clear objectives that relate directly to an organization’s enterprise strategy and track closely to key performance indicators (KPIs) for the business at large.

In order to start the conversation about an API strategy, business stakeholders may consider asking questions about the target market, the product offer, the competition in the API space, and the API product’s points of parity and points of differentiation.

Strategy Components

1. Vision

The vision statement defines the top priorities: what must be done, and more importantly what should not be done

2. Product Management

Companies need to determine very early on if the APIs they are producing are going to be private or public, and determine the criteria to differentiate between them.

Private APIs

Strategic goals for private APIs may be to increase business agility, to foster innovation or to save money and improve efficiency. It is also important to determine how legacy applications will be migrated to the API based architecture Note: Private APIs may become public APIs at any point in time, one cannot assume that there will never be an external demand for APIs initially deemed useful for internal consumption only.

Public APIs

When planning the strategy for public APIs, one has to determine the role the public APIs will play in the overall product and marketing strategy, and to decide if the company will develop one set of APIs only, that are consumed both internally and externally. The introduction of APIs as a distinct product will trigger a competition between end-user products and developer products. This tension has to be acknowledged and managed from the start of the API program.

Questions to consider from a product perspective:

• Will all the APIs be one product? If so, it is the duty of the product managers to seek consistency and alignment from the independent agile development teams
• Will there be tiered offerings?
• If there is competition in the API space, what are the points of parity with the competition?
• What are the points of differentiation from the competition?

3. Governance

Outlines the key guidance elements for API design, API security and how to document and present the APIs to the target market consistently across teams and products. Consider defining and using API design standards consistently across the organization. Open source inspirations abound, check the one published by Zalando.

4. Developer Community Support

Successful API adoption depends not only the quality of the APIs or the data they provide access to, but also how strong the community support is, which is determined by the funding allocated to it.

The API documentation is the first step towards engaging a developer community, and the organization need to invest into means to share it securely. In addition, making sandboxes available to business analysts and developers to test the APIs will increase customer satisfaction.

Developers of API clients need to be empowered to learn about the API contracts, and be able to test them with ease. Providing API definitions using standard formats, for example the Open API Specification allows consumer of the APIs to develop client code faster, by leveraging code generation tools.

There are many products available to publish API specifications, some of them integrated with run-time environments e.g. MuleSoft suite of products, Apigee, Azure API management platform. Other products are stand alone, e.g. Stoplight or Swagger, now part of Smart Bear family.

5. Training

REST API design is very different from object oriented design and it takes considerable effort to understand the subtle differences between the two design paradigms. Investing in training of the senior technical staff will accelerate the velocity of high quality API design and development. Sharing the same knowledge space will allow teams to align organically in the design patterns they chose to use, resulting in highly cohesive API products which increase customer satisfaction.

6. Security

Ideally, all APIs developed by an organization will use the same security mechanisms for authentication and authorization. The industry has converged towards the use of OIDC and JWTs, but these may have to be supplemented by other measures, e.g. API Keys for tenant access, and mTLS for channel security.

Questions to consider when deciding on the API security model:

• Is the security model of the public APIs different from the private APIs?
• If not identical, where are the differences stemming from?
• Why are there any differences?
• Can be differences be moved to the claims of the JWT?

7. Version Management

API clients need reassurances that the APIs they use are stable, than new versions of the APIs will be backwards compatible, and that the deprecation policies are clearly stated.

8. Lifecycle Management

An API cycle involves activities such as design, development, testing, deployment, operations and deprecation; an enterprise needs to support running multiple major versions of APIs in parallel, according to the API version management policies.

Corollary

Small single teams, that develop products using a microservice architecture style and mobile or Single Page Application front ends, don’t need a formal API strategy, as they are able to manage APIs by using yaml file definitions stored in GitHub together with the source code.

At the other end of the spectrum, companies with a large number of teams developing APIs in parallel may consider a wider API strategy as described above.

In both cases, success is measured using well designed metrics, such as number of clients using the APIs, the revenue obtained from APIs, the business agility gained from using APIs, stability of the product,….