Blueprint: Everything but the Kitchen Sink

Contains all of the elements grouped by some of the common areas of the API lifecycle.

This Blueprint is Still in Draft Mode and Will Be Rapidly Changing!

At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis praesentium voluptatum deleniti atque corrupti quos dolores et quas molestias excepturi sint occaecati cupiditate non provident, similique sunt in culpa qui officia deserunt mollitia animi, id est laborum et dolorum fuga. Et harum quidem rerum facilis est et expedita distinctio. Nam libero tempore, cum soluta nobis est eligendi optio cumque nihil impedit quo minus id quod maxime placeat facere possimus, omnis voluptas assumenda est, omnis dolor repellendus. Temporibus autem quibusdam et aut officiis debitis aut rerum necessitatibus saepe eveniet ut et voluptates repudiandae sint et molestiae non recusandae. Itaque earum rerum hic tenetur a sapiente delectus, ut aut reiciendis voluptatibus maiores alias consequatur aut perferendis doloribus asperiores repellat.


Define

Ensuring that operations supporting an API is properly defined, as well as what is needed to properly design and bring an API to life. A little planning and organization at this step of an APIs journey can go a long way towards ensuring the overall health and velocity of an API, and the applications that depend on this internal, partner, or public API.

  • Overview - Providing a single overview of an API so that all the moving parts of an API viewed in a single dashboard helps ensure that all team members will be able to get up to speed on the overall picture of an API in a way that doesn't require another meeting.
  • Private Workspace - There will be APIs that require limited visibility across teams depending on where it is at in it's lifecycle, or the nature of resources or capabilities it provides access to, making a private workspace something that is necessary to tightly control who has access and visibility.
  • Team Workspace - Establishing and properly setting up a dedicated workspace for each API helps ensure there is always a single place to go to find everything that is happening with an API across it's entire lifecycle.
  • Partner Workspace - A workspace just for a specific partner or group of partners, providing an invite only location to collaborate around the production or consumption of an API, making API operations accessible to trusted partners, but not to the general public, establishing a trusted space for the iteration and integration with an API.
  • Public Workspace - Some APIs will benefit from establishing a public workspace where 3rd party consumers can learn about an API, view the moving parts of it's operation, and engage with the team behind, making the API lifecycle much more transparent.
  • Roles - Identifying the roles of each team member working on an API helps establish clear directives for who can make changes to an API, something that can drive and configure other elements applying to an API across the lifecycle.
  • Github Repository - Having a dedicated Github repository for an API provides a single place where code and other artifacts can be managed, with a pipeline, issues, and other supporting elements an API will need to operate.
  • Bitbucket Repository - A dedicated Bitbucket repository for an API provides a single place where code and other artifacts can be managed, with a pipeline, issues, and other supporting elements an API will need to operate.
  • Gitlab Repository - Having a dedicated Gitlab repository for an API provides a single place where code and other artifacts can be managed, with a pipeline, issues, and other supporting elements an API will need to operate.
  • Use Cases - Establishing a list of real world business uses cases of an API helps clarify the purpose an API, ensuring that the design and development of the API matches the business objects, and the needs of potential consumers.
  • Goals - Ensuring the goals behind an API are well defined and accessible as part of the operation of an API help ground a team's activity when it comes to supporting consumers and iterating upon API, helping ensure that the API design and operation is in alignment with business objectives.
  • Relationships - Defining and understanding the way in two concepts, objects, or people are connected with APIs, helping connect the dots between the more human and business operations side of how APIs work, acknowledging that people and process are a critical part of how APIs work, and will influence there usage and evolution over time.
  • Environments - Machine readable environments for APIs allow for abstracting away common elements of an API environment from the definition of each API, allowing different environments to be paired with OpenAPI and collections for each API at design, develop, and build time.
  • Environments - Machine readable environments for APIs allow for abstracting away common elements of an API environment from the definition of each API, allowing different environments to be paired with OpenAPI and collections for each API at design, develop, and build time.
  • Schema - Defining all objects use as part of API operations using JSON Schema provides for a definitions that can be used as part of modeling and the API design process, as well as for validation at development, build, or even run time.
  • Examples - Examples of API request, responses, and messages used across API operations helps provide a versioned, evolvable, and reusable set of example and synthetic data that can make documentation richer and testing more relevant to actual business needs.
  • Data Sources - Providing the sources of where an API retrieves it's data, mapping the API to backend databases that contain the actual resources that will be made available via each API, allowing each API to be able to find data as requests are made by consumers.
  • Role Based Access Control - Role based access control allows for the artifacts and elements for each API to have clear team access to only viewing and running or being able to actually edit and change, helping prevent unwanted changes to API elements across the lifecycle.
  • OpenAPI - The OpenAPI specification provides a common vocabulary for describing the surface area of request and response APIs, as well as webhooks, ensuring that API producers and consumers are on the same page when it comes to integration, but also helps stabilize multiple areas of the API lifecycle providing a contract that can be used for delivering documentation, mocks, testing, and more.
  • AsyncAPI - AsyncAPI is a machine readable specification for describing the surface area of your asynchronous APIs. OpenAPI is meant for describing synchronous APIs like REST using HTTP, and AsymcAPI is for describing websockets, MQTT, Kafka, NATS, and other syncrhonous, event-driven, and message APIs.
  • WSDL - WSDL is an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information, providing the operations and messages are described abstractly, and then bound to a concrete network protocol and message format to define an endpoint.
  • Scripts - Lightweight scripts that can be run as part of each API request, providing pre-request scripting, or post-request scripting that help appy business logic at either end of the request, helping transform, test, and automate with each API request.

Design

Having a formal process and approach to designing an API helps establish consistency and the precision of APIs in production, ensuring that APIs are developed using common patterns across an industry, and within an organization, establishing known practices for shaping the surface area and behaviors of APIs that applications are depending upon.

  • Prototype Collection - Prototyping an API using a Postman collection provides a quick and intuitive way to articulate what an API should do in a way that can be documented, mocked, and shared with other team members and consumers, offering an alterative approach to the API design first methodology which can push the need for an OpenAPI artifact further downstream in the process, but achieving similar outcomes.
  • Workflow Collection - Defining workflows across many APIs and API paths provide a rich way to design and document common business workflows and practices, providing a specific sequence of API requests needed to accomplish a business objective, or just a subset of a larger API that meets the needs of a specific business sector, helping go beyond just a reference of everything an API does and getting closer to the business value.
  • OpenAPI - The OpenAPI specification provides a common vocabulary for describing the surface area of request and response APIs, as well as webhooks, ensuring that API producers and consumers are on the same page when it comes to integration, but also helps stabilize multiple areas of the API lifecycle providing a contract that can be used for delivering documentation, mocks, testing, and more.
  • AsyncAPI - AsyncAPI is a machine readable specification for describing the surface area of your asynchronous APIs. OpenAPI is meant for describing synchronous APIs like REST using HTTP, and AsymcAPI is for describing websockets, MQTT, Kafka, NATS, and other syncrhonous, event-driven, and message APIs.
  • WSDL - WSDL is an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information, providing the operations and messages are described abstractly, and then bound to a concrete network protocol and message format to define an endpoint.
  • Design Patterns - Utilizing common design patterns and standards for the design, development, and operation of APIs helps ensure APIs leverage a common vocabulary and increases the chances that consumers will understand how to put an API to work in their applications, increasing the effectiveness of an API, and helping increase the productivity and velocity of producers and consumers.

Mock

Mocking how an API works and behaves provides an effective way for teams to collaborate, communicate, and iterate as part of the design of an API, but also is something that can be used as part of testing, or just providing a sandbox environment for API consumers to learn before they actually begin working with any API in production.

  • Mock Server - A mock server helps replicate as much of the functionality and API would have in production, before the time to actually have to write any code, making APIs be more tangible and real early on in the lifecycle, allowing teams to rapidly design an API that meets the needs of everyone involved, providing usable elements that power design, documentation, testing, and other elements of the API lifecycle.
  • Examples - Examples of API request, responses, and messages used across API operations helps provide a versioned, evolvable, and reusable set of example and synthetic data that can make documentation richer and testing more relevant to actual business needs.

Document

Having complete, accurate, and easy to follow document is essential for all APIs, helping alleviate the number one pain point for API consumers when it comes to onboarding with an API, as well as expanding the number of API paths an application puts to work, making API documentation one of the most important areas of the API lifecycle.

  • Reference Documentation - It is helpful for API consumers to have complete documentation for the entire surface area of an API, providing a complete reference of what is possible with an API to help consumers explore every path, parameter, schema, and other details of how an API works, making the resources and capabilities available within API something consumers can find and put to use without much work.
  • Onboarding Documentation - It can be helpful to provide new users with documentation designed specifically for onboarding new consumers to an API, only introducing them to the most relevant paths of an API, reducing the cognitive load when it comes to getting started with an API and complimenting more complete reference documentation showing everything that is possible with an API.
  • Workflow Documentation - Providing documentation for workflow collections help introduce consumers to what a workflow define across multiple API requests can accomplish, and potentially provide a sequential walk through of each step of the flow, allowing API consumers to quickly understand what a workflow accomplishes, but also provides all the details of the workflow in an well documented executable format.
  • Examples - Examples of API request, responses, and messages used across API operations helps provide a versioned, evolvable, and reusable set of example and synthetic data that can make documentation richer and testing more relevant to actual business needs.
  • Code Annotations - Language specific code annotations can be used to generate OpenAPI definitions for APIs in a variety of programming languages, allowing developers to provide the necessary information to create an APi contract from within their natural development environment, embracing a code-first approach to the API lifecycle while still ensuring there is an OpenAPI to be used for the rest of the lifecycle.
  • Interceptor - Running traffic through Interceptor in Chrome to capture API traffic, allowing the details of requests and response to be translated into a collection that can be re-run, organized, shared, monitored, automated, and put to work consuming API resources, or even used to inform the evolution of an API by defining the surface area of each API based upon how it is used.
  • Proxy - Running traffic through a proxy to capture activity to capture the details of each request and response, then generating a collection that provides a machine readable and executable representation of API traffic that can then be executed, tested, automated, monitored, and documented as part of the production or consumption of APIs.

Test

A test-driven API lifecycle ensures that each API accomplishes the intended purpose it was developed for, providing manual and automated ways to ensure an API hasn't changed unexpectedly, is as performant as required, and meets the security expectations of everyone involved, helping establish a high quality of service consistently across all APIs.

  • Contract Testing - Contract tests can be derived from API artifacts like OpenAPI, JSON Schema, and GraphQL, and used to ensure there are no changes to what has been promised when an API was designed or developed, providing a repeatable test that can be run manually, on a schedule from multiple regions, or as part of a CI/CD pipeline to ensure contracts with consumers are upheld.
  • Performance Testing - Performance tests can be defined as individual tests using collections, pulling from one or many individual API paths and measuring the time it takes for the response to be sent, providing a test that can be run manually, scheduled across multiple geographic regions, or executed as part of a CI/CD pipeline, helping ensure an API is always meeting it's expected performance benchmarks.
  • Security Testing - Security tests can be defined for any API using executable and shareable collections, testing for common OWASP vulnerabilities, as well as other more custom scenarios or business approaches, providing a single or suite of security tests that can be manually run, schedule across multiple regions, or executed as part of a CI/CD pipeline, automating security consistently across APIs.
  • Workflow Testing - Establishing tests for specific business workflows helps to ensure that critical business capabilities are always available, defining simple or complex scenarios that mimic real world functionality complete with synthetic or actual data to try and make sure the tests reflects what will actually be happening in real life.
  • Integration Testing - Integration tests can be defined for any API using executable and shareable collections, testing integrations, as well as other more custom scenarios or business approaches, providing a single or suite of integration tests that can be manually run, schedule across multiple regions, or executed as part of a CI/CD pipeline, automating integration testing consistently across APIs.
  • Linting - Validating an API schema against a known set of constraints, ensuring that all artifacts in use across API operations are well defined and match known and intended schema for use as part of requests, responses, and the messages being sent, published, and subscribed to across API operations.
  • Scripts - Lightweight scripts that can be run as part of each API request, providing pre-request scripting, or post-request scripting that help appy business logic at either end of the request, helping transform, test, and automate with each API request.

Deploy

Establishing a well defined process for deploy an API helps teams deploy new APIs, as well as each future iteration of an API in a consistent and repeatable way, making sure APIs are deployed using known development, staging, production, other agreed upon stages that actively put to work the other elements like documentation, testing, while contributing to observability.

  • Gateway - API gateways provide a centralized or federated approach to the deployment and management of APIs at scale across an organization, leveraging commercial or open source API gateways to deploy APIs into development, staging, production, or other environment, allowing for the standardization of common elements of API management, and configuring APIs using common policies.
  • Business Logic - The custom rules or algorithms that handle the exchange of information between a database and user interface, defining the logic that exists in between APIs and backend systems, allowing data, content, media, and other resources to be transformed, remixed, and personalized for consumers, optimizing the overall experience.
  • Resolvers - The bindings that map incoming queries to specific data sources so that APIs know where to find resources, distilling down API requests into meaningful queries that will make sense to backend systems, connecting the front end requests to the backend stores, routing API requests to where they need to go.

Code

Providing either server or client side code that helps make it easier to produce, consume, and integrate with APIs, helping reduce friction and increase velocity of teams by providing many of the common needs developers will need to put APIs to work across operations.

  • Code - Instructions for a computer program in any language that can be used to power APIs on the back or integrate, automate, and orchestrate on the client side, providing executable instructions that accomplish a specific business object, providing what operations needs to power information technology across an organization.
  • Client SDKs - The software development kits (SDKs) in a variety of programming languages that API consumers can use to bootstrap their application development and integrations, helping reduce friction when it comes to developers building on top of APIs.
  • Client Snippets - Simple easy to apply snippets of code in a variety of programming languages for each individual API request, providing ready to go resources for developers to use when learning about how an API works, while also potentially jump-starting integration and putting to use in applications.

Manage

APIs should be managed using a set of common, well-defined policies that define and govern how APIs are access via all stages of the lifecycle, and ensure that every API has relevant authentication, rate limits, logging, and other essential aspects of managing APIs at scale, helping strike a balance between making APIs accessible and the privacy and security concerns that exist.

  • Onboarding - Offering a consistent and well defined onboarding experience for all APIs, making it as easy and straightforward for consumers to onboard with an API, while also providing API producers with an easy way to onboard new consumers with their APIs without any custom work required, reducing friction when it comes to putting APIs to work by utilizing well known approaches to onboarding.
  • Authentication - The consistent application of standard authentication as part of a standardized API management layer striking a balance between access to digital resources but ensuring that undesirable actors do not have access to valuable assets.
  • Usage Plan - Offering a standardized and well-defined set of usage plans for all APIs using commercial or open source API gateway or management solutions helps ensure that access to all APIs is done in a secure way that prevents exploitation by limiting the number of requests being made, or even billing for usage of an API based upon different dimensions defined within the usage plans applied.
  • Key - API keys provide the simplest form of access to an API, allowing consumers to sign up for an account, define what their application is, and then receive a key they can include in headers or other parameter to identify themselves, ensuring that API producers are fully aware of everyone who has access to an API, and all consumers have a way to clearly identify themselves and receive personalized usage data for each key.
  • Applications - Desktop, web, mobile, device, or network applications that apply API resources and capabilities delivering the intended business value of API resources and capabilities, putting individual or series of API requests to work powering business operations.
  • Automation - Automated production or consumption of API resources, allowing for repeatable API-driven processes to be triggered or scheduled, allowing teams to define and set into motions certain aspects of operations while focusing on the more manual, creative, and human aspects of doing APIs.
  • Client - A web or desktop client for making calls to APIs, providing a way for anyone to make requests or publish messages to APIs, see the responses, and put APIs to work without having to write code, helping make authentication and other recurring aspects of API usage easier.

Monitor

All tests applied to an API should be monitored on a logical schedule and from relevant geographic regions, monitoring that APIs aren't breaking their contract, falling below their agreed upon service level agreement (SLA), or becoming a security risk, helping automate the quality of service across APIs in a way that allows teams to be as productive as possible.

  • Monitor - Monitoring any process across API operations defined as a collection, then bundled with any environment, setting a schedule for the execution of the collection, and viewing or publishing of the results to any other location, providing a very wide definition of what monitoring can mean across API operations.
  • Contract Testing Monitor - Monitors can be setup for all API contract testing, scheduling the run of contract testing when needed and configuring to run from the regions that matter most to business operations, making sure that each individual API contract is never breaking with consumers, making sure that each API is delivering as expected on a 24/7 schedule.
  • Performance Testing Monitor - Monitors can be setup for all API performance testing, scheduling the run of performance testing when needed and configuring to run from the regions where performance makes the most difference on business, making sure that each individual API SLA is met, identifying API performance issues early on and responding to ensure there is no significant business impact.
  • Performance Testing Monitor Results - The results of any performance testing run can be rendered as test results, presented using visualizer, and posted to existing APM or other destination that can be used as part of wider observability systems, allowing performance tests across all APIs to be centralized for understanding API performance at scale.
  • Security Testing Monitor - Monitors can be setup for all API security testing, scheduling the run of security tests when needed, making sure that each individual API is regularly certified as being secured, ensuring that APIs do not become a liability due to changes, but also keeping all APIs compliant with the latest level of security testing that is occurring across an entire organization.
  • Workflow Testing Monitor - Monitors can be setup for all workflow testing, scheduling the run of workflow tests when needed and configuring to run from the regions that matter most to business operations, making sure that essential business capabilities are working as designed and delivering as expected on a 24/7 schedule.
  • Uptime Testing Monitor Results - The results of any uptime testing run can be rendered as test results, presented using visualizer, and posted to existing APM or other destination that can be used as part of wider observability systems, allowing uptime tests across all APIs to be centralized for understanding API performance at scale.

Automation

Automating producing or consumption of API resources and capabilities, allowing for repeatable API-driven process to be triggered, scheduled, or respond to events, allowing for teams to properly define and set into motions certain aspects of operations while they focus on the more manual, creative, and human aspects of doing APIs.

  • Monitor - Monitoring any process across API operations defined as a collection, then bundled with any environment, setting a schedule for the execution of the collection, and viewing or publishing of the results to any other location, providing a very wide definition of what monitoring can mean across API operations.
  • Scripts - Lightweight scripts that can be run as part of each API request, providing pre-request scripting, or post-request scripting that help appy business logic at either end of the request, helping transform, test, and automate with each API request.
  • Newman - Newman is an open source collection runner, allowing Postman collections to be executed as part of CI/CD pipeline runs, executing all of the API requests, pre-request, and post-request scripts, and providing results reporting that can be used as part of testing and automation.

Discover

The ability to discover APIs at all stages of the API lifecycle is key to reduce redundancy across operations, helping teams find existing APIs before they develop new ones, and properly match API consumers with the right APIs, supporting documentation, relevant workflows, and the feedback loops that exist as part of the operation of APIs internally within the enterprise, or externally with 3rd party developers.

  • Private Network - Private API networks all organizations, groups, and teams to establish private catalogs of APIs, collections, and the other artifacts and elements around them, making it easier for producers and consumers to find APIs that are being designed, developed, or operating in production, making APIs more accessible but only to an intended audience.
  • Public Network - Public API networks allow for teams, APIs, collections, and other elements to be made available for searching and browsing by a public audience, helping API producers reach a larger audience, but also allowing consumers to quickly find the APIs and other resources they need in their applications and integrations, networking consumers with producers in an ongoing and collaborative way.
  • Search - Ensuring APIs are always available via search helps make sure that APIs can be found by consumers, but also by other producers who are looking to develop similar APIs, making search for APIs, as well as the operations around each API a critical aspect of the API lifecycle that should be considered as early on in the design and development of an API, but at least as it is deployed into production.

Security

Ensuring that all digital resources and capabilities are properly secured from end to end, making sure proper identity and access management, vulnerability scanning, and other common approaches to securing infrastructure on the Internet is in place and properly maintained.

  • Secure - Ensuring that an API is secure from threats and vulnerabilities, making for a pretty wide spectrum of different processes and technologies that ensure digital resources and capabilities made available via APIs are only accessible to an intended audience and bad actors are not able to find ways to get access via an API.
  • Role Based Access Control - Role based access control allows for the artifacts and elements for each API to have clear team access to only viewing and running or being able to actually edit and change, helping prevent unwanted changes to API elements across the lifecycle.
  • Authentication - The consistent application of standard authentication as part of a standardized API management layer striking a balance between access to digital resources but ensuring that undesirable actors do not have access to valuable assets.
  • Security Testing - Security tests can be defined for any API using executable and shareable collections, testing for common OWASP vulnerabilities, as well as other more custom scenarios or business approaches, providing a single or suite of security tests that can be manually run, schedule across multiple regions, or executed as part of a CI/CD pipeline, automating security consistently across APIs.

Observability

Tapping into the outputs available across API operations to understand what is happening with individual APIs throughout their lifecycle, but also in aggregate for domains, teams, and other logical groups, helping make API operations more visible in real time.

  • Activity - The changes made to any aspect of operations by team members, providing observability into when APIs, mock servers, documentation, testing, monitors, and other critical elements of API operations are changed, configured-- helping give a log of everything that happens at the operational level.
  • Reports - Visual reports that aggregate data from across operations, making APIs and the operations around them something that team members can see activity, hisotry, and other dimension of what is happening across API operations, allowing different views to be organized and presented via dashboards.
  • Change Log - A detailed history of the changes that have been made specifically to an API, showing all of the changes to the structure of an API as part of the design and development process, providing a single list of what has changed for consumers, and other stakeholders to get up to speed.
  • Audit - Auditing the usage and operations of each API, or a group of APIs to understand how APIs work, what dependencies are to understand the actual state of any part of API infrastructure is performing or under-performing, to better inform the road map for API operations.
  • Gateway Usage Report - A usage report for an API provided by the gateway, providing data regarding consumption of API resources and capabilities, offering detailed or aggregate views of what is happening with each API and across operations, providing observability into how APIs are being put to use within applications and as part of integrations.
  • Contract Testing Monitor Report - A report that allows the one time or historical results of contract testing monitors to br visualized, providing visibility into whether or not an API contract has been broken at any point in time as defined the schedule of the contract testing monitor runs.
  • Application Performance Management (APM) - The monitoring and management of performance and availability of APIs, actively detecting and diagnosing performance problems to maintain an expected level of service, translating API operational metrics into business meaning value at scale across hundreds or thousands of internal or external APIs.
  • Intelligence - The acquisition of knowledge from across API operations, providing the data that is needed to make decisions regarding the operation and evolution of each API, ensuring that teams are well informed and have what they need to do what matters the most to business.

Communicate

Communicate with API stakeholders syncronously and asyncronously across the API lifecycle, localizing the conversation around what is happening around each API, while also allowing for seamless integration with exiting communication channels, allowing teams to efficiently share knowledge in the moment.

  • Notifications - Providing notifications about activity around the operation of any API, allowing for in-application, email, or type of message via integration with common platforms, providing real time updates about what is happening across API operations.
  • Comments - Comments on APIs, collections, and other elements of API operations allows for more tightly coupled and inline conversations to occur around entire elements or specific parts nd pieces of elements, allowing teams to collaborate and communicate across the API lifecycle.
  • Inform - Ensure that all stakeholders for an API have all the relevant facts and information regarding an API, keeping teams behind APIs up to speed all what they need to know to design, develop, and manage an API across it's evolution, allowing everyone to make the best possible decisions when it comes to delivering APIs.

Collaborate

Collaborating across teams and lines of business to securely share artifacts from across API operations, providing more visibility across the workspaces where developers are already producing and consuming APIs, while providing many different types of collaboration opportunities as they work.

  • Sharing - Sharing of elements used to produce or consume APIs across workspaces, externally with consumers, allowing an intended audience to view, download, and access artifacts and other elements of API operations so they and collaborate around the production or consumption of API resources and capabilities.

Governance

Defining all the practices and process across the organization for delivering APIs, establishing well known and communicated areas, elements, and actions that shape how API operations function, providing all teams with what they need to effectively deliver API infrastructure from start to finish.

  • Design Patterns - Utilizing common design patterns and standards for the design, development, and operation of APIs helps ensure APIs leverage a common vocabulary and increases the chances that consumers will understand how to put an API to work in their applications, increasing the effectiveness of an API, and helping increase the productivity and velocity of producers and consumers.
  • Documentation Rules - Machine readable or codified rules that govern whether or not documentation exists for each API, making sure there is accessible HTML documentation available for API consumers, and even validating there are examples, and other specific parts of API documentation present.
  • Management Rules - The governance rules to apply to API management, ensuring that policies are being applied consistently across APIs, standardizing how APIs are managed in production, making sure there are limitations, constraints, and observability present across all APIs in ways that are defined as part of a centralized governance strategy.
  • Linting - Validating an API schema against a known set of constraints, ensuring that all artifacts in use across API operations are well defined and match known and intended schema for use as part of requests, responses, and the messages being sent, published, and subscribed to across API operations.

Retire

Having a plan for the eventual retirement and ultimate deprecation of an API, or for specific paths or versions of an API should be a part of every API lifecycle, even when there is no plan for deprecation there should be a process in place for setting expectations for how long an API will be supported, as well as formal process to follow once retirement comes into view on the horizon.

  • Retire - The retirement of an API or specific version of an API is an inevitable thing and there should be a formal process in place to inform API producers about what the steps are in a process to retired, and set in motion the deprecation of an API, keeping an API or version of an API active for a specific amount of time, while acknowledging that at some point it will go away.
  • Deprecate - API deprecation occurs eventually for all APIs, and having a formal process to the deprecation of APIs or specific versions of an API helps API producers prepare for this inevitable future in a way that keeps consumers properly informed about what is happening, allowing the deprecation of APIs to happen consistently across all teams, groups, and the entire enterprise organization.
  • Archive - Establishing a formal process for how APIs are taken down, stored, and kept for potential usage in the future, avoiding the deletion of each API soon as it is deprecated.


Discussions

YAML

Printable

Slide Deck

Return to Main Page

This provides a link back to the home page if you need it.