API Strategy

I recently assembled a strategy from the 400+ Spectral rules I have developed. I wanted to abstract away these rules I am using to automate API governance using two separate layers. 1) Policies, which are meant for product managers and other business stakeholders, and 2) Strategy areas, which are meant for business leadership. I went about things backwards (as I do), and created the rules, backfilled the policies, and then organized into a series of strategy areas.

These are the 29 strategy areas I’ve derived from the technical side of my API governance approach–they are generated from a YAML file and is the first time I am reading through as a single strategy.

• APIs are Defined as API Contracts - All APIs are defined as API contracts so that we can align both the business and technology of delivering consistent high quality APIs, employing source control to manage the technical, but also the business side of things, while actively checking in on the alignment between the two over time.
• APIs Possess Informative Metadata - All APIs possess metadata that is relevant to what APIs do, but also how they can be used in business by API consumers, and metadata helps ensure that the front door for API operations within this domain is always one click away, and present in all artifacts we use to support API operations.
• APIs Have One Click Access - All APIs possess a URL for humans to follow when engaging as well as the base path URL for machines to use when calling each API, ensuring that the front door for API operations within this domain is always one click away, and present in all artifacts supporting humans and the applications.
• API Paths Must Conform to the Organization - All API paths must conform to the overall organizational domain standards, utilizing plain language and a resourceful approach to delivering digital resources and capabilities via HTTP APIs, providing a common set of paths that can be used and reused across many different applications and consumers.
• API Operations Must Be Useful and Consistent - All individual API operations must be useful and follow consistent Internet, industry, and enterprise standards, providing a simple and relevant HTTP API operation that does one thing and does it well, making the value intuitive to API consumers who will be using each API operation.
• API Responses Must Be Meaningful and Consistent - All API responses should follow Internet, industry, and enterprise standards, providing a meaningful and consistent communication and structure, always providing what was intended for API consumers, while ensuring things are always as simple as possible–always reducing the cognitive load.
• API Data Should Be Well-Defined and Validated - The schema for data that is sent and received via API should always be well-defined, possess a well-known shape, and always be validated, ensuring that digital resources and capabilities are what they should be, and only accessible to those who should have access our API digital resources.
• API Operations Must Always Be Secure - Individual API operations should always be properly secured during design, develop, and run-time, making sure data, credentials, logs, and all other related resources are properly secured and operating as expected by both the API producer and the consumer–protecting both parties equally.
• APIs Must Reusable Whenever Possible - The components of any API should be made modular and reusable whenever it makes sense to the business use case, keeping schema, parameters, examples, error responses, and other common parts of an API as reusable and interchangeable as possible within a single API, but also across all APIs.
• APIs are Defined by Technical Contracts - All APIs must have machine-readable artifacts that defines the technical surface area of each API being made available to API consumers, utilizing open-source community specifications like OpenAPI and JSON Schema to define the technical details of each API that is being made available.
• APIs Are Always Well Documented - All APIs must have human-readable documentation that defines the technical surface area of each API being made available to API consumers, providing a simple, intuitive, and ideally interactive HTML representation of APIs, methods, operations, requests, responses, errors, and other elements.
• Producing APIs MUST Be Repeatable - All APIs must have a single source of truth for all artifacts, as well as the conversations and always be able to be delivered using a repeatable process, leveraging existing software development infrastructure to ensure for continuous integration and delivery consistently across all APIs.
• APIs Are Made Available Through a Platform Gateway - All APIs must be deployed through a common platform gateway established for the domain, line of business, or team, leveraging development, staging, and production environments, and a common set of policies for configuring access to digital resources and capabilities via APis.
• APIs Are Always Aligned with Business - All API contracts must have use cases that align the business reasons why an API is being delivered to consumers with the actual technical details of each API contract, ensuring that operations all have a valid business use case.
• APIs Are Aligned with Industry Using Standards - All APIs must be using relevant Internet, industry, and government standards available, ensuring to properly research areas of operations to see what existing standards may exist before the creation of any new schema or process, helping align operations with the wider industry API landscape.
• Change is Actively Managed for Each API - All APIs must have change management baked into the definition, delivery, and iteration, ensuring that producers and consumers are in alignment regarding the communication, quality, and velocity of change that is occurring for each individual API, driving planning as well as API provenance.
• APIs Are Always High Quality and Reliable - All APIs should be high quality and reliable, providing adequate levels of monitoring of its availability and performance, with the proper provenance and communication with producer and consumers regarding quality of the APIs, as well as with any future release of API resources.
• APIs Always Have Well-Defined Owners and Stakeholders - Each API should ideally have a dedicated product as well as an engineering owner, with other stakeholders across the API lifecycle defined in an easy to access human readable location, but also defined in a machine-readable API to help automate coordination amongst owners and stakeholders.
• APIs Operations Possess Dedicated Workspaces - API operations should provide dedicated workspace for domains, lines of business, and teams who are producing APIs, providing a dedicated location where work, collaboration, and automation can occur around APIs establishing the virtual factory floor that exist across enterprise API operations.
• Onboarding is Always as Easy as Possible - API operations is made easier by making common elements like documentation, authentication, SDKs easy to find and available as just a couple of simple steps that API consumers can follow when it comes to onboarding with an API, helping producers simplify the onboarding for their consumers.
• API Change is Relative to Operational Change - Individual APIs should be aligned with overall operational change, providing a common operational change log and road-map that is higher level than change for each individual API, but provides a common context across all APIs, teams, and lines of business–keeping everyone in alignment.
• APIs Work Across Multiple Programming Languages - All APIs should have SDK and other client or server code available in multiple programming languages used by targeted API consumers for known business use cases, making it as simple as possible for consumers to put an API to use in their own language and frameworks, via their own infrastructure.
• APIs Are Legally Covered - All APIs must be reviewed by legal council and posses terms of service, privacy policy, licensing, and other regulatory and compliance requirements, making sure all the legal bases are covered before any API is made available to any external consumers of digital resources.
• APIs Must Be Actively Governed - All APIs being produced must be governed as part of the overall strategy, using the platform, as well as a common API lifecycle, applying policies and rules, and keeping teams moving in the same direction using guidance, and speaking the same language with a common API vocabulary.
• APIs Are Part of Regular Active Communication - All APIs are considered and included as part of regular internal and external communication channels, sharing road maps, change logs, blog posts, videos, and other relevant information that producers and consumers will find useful around their regular technical or business applications.
• APIs Must Be Supported and Have Feedback Loops - All APIs must have support mechanisms to ensure API consumers have self-service or direct support channels, as well as regular feedback loops for soliciting feedback or answering specific API questions from consumers, going beyond the problems consumers may have encountered using APIs.
• API Contracts Are Validated - All APIs must have a link to the evidence of the contract validation for business and technical contracts, allowing any stakeholder to review the details of the contract, as well as the rules applied to govern the details of contracts.
• A Common API Lifecycle - This is the API lifecycle being applied to this API, organizing the policies above by each stage of API development, rather than by strategy area, helping understand when things need to happen, and automating the governance of APIs by each individual stage.
• A Common Engineering Platform - This is an index of all of the infrastructure and services used to operate the engineering side of APIs.io, providing a single manifest of all the 3rd-party suppliers we depend on for digital resources and capabilities. The goal of this engineering platform definition is to define the platform in a way that can be federated and distributed as part of API operations, helping educate teams where they can access platform resources.

It needs a lot more work as a whole strategy, but still reads pretty well considered it was reverse engineering from 400 Spectral rules. Guarantee it reads better than all of the policies and rules that can actually execute on this strategy across many different HTTP APIs. It is the first time I was able to connect the ground floor with the top floor.

I will write a blog post for each of these areas, and work my way back down to the factory floor, thinking through the policies and rules that define, enforce, and automate API governance in each of these areas. There is a whole lot of more work in there on the strategy, policy, rules, and guidance, but the framework is there. I will keep applying heavily to APIs.io and API Evangelist APIs, as well as my clients, but then also do lightly as part of my APIs.io profiling–further fleshing out what an API strategy looks like.