Defining API guidelines and creating tooling for checking and complying with those guidelines are important. They’re key milestones in any team’s or organization’s API journey.

But what are the other capabilities that constitute a complete API platform?

Not every organization needs every capability, but it’s beneficial to have a view of the overall landscape. In this post, we take a “mile wide and inch deep” look at the potential capabilities in an API platform, shown in the graphic below, and how they relate to each other (click image to view larger).

The advantages of having a capability reference resource is that it helps teams:

• Identify the most important capabilities (the “must-haves”) when an organization starts on its API journey, as well as the ones to consider later
• Explore external commercial/free tools that support the needed capabilities
• Assess if multiple capabilities from the same vendor can be leveraged for optimal cost

There are two overarching concerns that should shape an API platform’s evolution: business strategy and technical strategy.

Business Strategy

• What are the business objectives and drivers?
• What are the high-level requirements?
• What are the timelines?
• What are the associated (opportunity) costs and risks?
• Is there alignment from stakeholders on the vision for the platform?
• What is the API delivery roadmap?

This should be the guiding light for your API platform. Moving directly to the technical strategy/implementation without a clear business strategy will likely lead to failure.

Technical Strategy

• How will the business goals be achieved through tech components in an optimal way?
• How are technology choices affected by constraints on resources/time/skills?
• Your approach for public vs. internal APIs.
• The following considerations/deliberations, which you’ll need to make:
  • Build vs. buy vs. use OSS for a capability.
  • Self-host and manage vs. SaaS vs. a hybrid offering.
  • What will be automated vs. manual?
  • Choice of tech stack(s) for any capability that will be built.
  • Choice of vendor(s) for a capability that will not be built.
  • Single offering from a vendor for all/most capabilities vs. mix and match capabilities from different sources.

Key Capabilities of API Platforms

Documentation/Developer Portal — This is the most important capability from an API consumer’s perspective. It enables API consumers and app developers to discover and work with APIs and associated assets (SDK, Postman collections, code snippets, support forums, etc.). API management solutions typically include a developer portal.

Product Manager — This is the most important capability from an API product manager’s perspective. It provides UI/API/declarative means to configure policies on APIs, create product groupings, do lifecycle operations, monetize APIs, and more. API management solutions include an API (product) manager.

Traffic Manager — A traffic manager is the run-time that enforces all policies configured by an API manager. This is an central part of an API management solution. There are also many standalone, battle-tested, open-source API gateways available that you can use to create a custom API management solution.

Analytics — This capability is relevant and useful to different audiences, including API developers, app developers, API managers, and operations teams. The types of reports/metrics include API usage, errors, performance, top users, revenue, and others. This capability is closely coupled to the gateway, which feeds the data.

Org/Env/User Mgmt — The API management solution will typically be used by multiple business units/services/geos and will need to have the constructs to group and isolate one set of users from others in a safe way. Also, it’s common to have multiple environments for development, testing, staging, and production, which should be achievable with the solution.

API Access — All or most of the API platform’s capabilities should be accessible via APIs for DevOps/automation purposes and for creating custom applications.

Abstraction API — Creating an abstraction API on top of APIs exposed by an API management solution can serve important purposes like:

• Avoiding tight coupling with a particular solution, which may get swapped out later.
• Exposing higher-level APIs, which are easier to consume in DevOps integrations and custom applications.
• Providing a multi-tenancy abstraction on top of a solution that is single-tenant.

Design Tools — These are sets of capabilities used by API designers. The capabilities include an editor to create/view API specs, auto-generation of mocks to play around with, a tool for reviews and approvals of the API workflow, guidelines compliance validation, backward compatibility validation and recommendations based on other APIs, existing domain models, and API usage history.

Implementation Tools — These are capabilities for use by those implementing or developing APIs. The capabilities include code generators for the service code, client-side SDK, test cases, helper libraries for implementation of APIs consistent with guidelines, test (functional/performance/contract) automation, and customizers for SDK when general purpose SDK generators are used.

Deployment Tools — These are the capabilities for implementing CI and CD of API proxies, documentation, and implementation. Artifacts need to be checked for integrity, consistency with guidelines, and any potential issues related to security (for example, APIs without authentication), usage (for example, APIs without rate limits), performance (response time > acceptable limit), and more.

API Implementation Hosting — The implementation of the API business logic needs a run-time stack and hosting. This could be any public cloud or a private data center.

Ops Tools — These capabilities are important to API operators and enable monitoring of APIs, setting SLAs and alerts, generating custom reports, auditing all actions on the platform (for example, lifecycle events), detecting threats (bots/DDoS, etc.), and taking remedial steps.

Enablement Docs — With so many rich capabilities on the platform, there is need for documentation like playbooks, example code snippets, starter repos, best practices, tool recommendations that cover how to get the most out of these capabilities,

Support/Governance — This includes channels, people, and processes for support and governance throughout the API lifecycle.

API Artifacts — All API artifacts like proxy config, documentation, and implementation need a version-controlled repo to live.

Processes/Workflows — In addition to the above capabilities, an API platform needs to define processes/workflows for the following actions:

• Onboarding a new service provider (team) on the platform
• Onboarding a new API on the platform
• Adding new geo/region support in the platform
• API review and approval process
• API deprecation process
• Onboarding a developer
• Onboarding a partner

In our next blog, we’ll look at some dos and don’ts when evaluating commercial/free solutions to build an API platform. And please check out the other blogs in our series:

• How is your API experience?
• Defining API guidelines for a company: What works?
• Best practices for validating your APIs against company guidelines