API Lifecycle Workshop

This is the home page for conducting an API lifecycle workshop using this API demo, providing a single landing page attendees can use when navigating the moving parts of this workshop, and come out the other end with a human, and machine readable strategy for executing on the delivery of APIs across any company, organization, institution, or government agency.

This API lifecycle blueprint provides guidance in five distinct areas of the API lifecycle, which can be operated individually for a single API, or in unison across many APIs, helping flesh out a standardized approach to thinking about how APIs are delivered across an organization. This isn't meant to be a one size fits all strategy, but a walk through of what is possible, that can be added to, and customized to make fit the specific needs of an organization.

  • Discovery (Jump To) (Presentation) - Knowing where all of your APIs and services are across groups.
  • Design (Jump To) (Presentation) - Focus in on an a design and virtualized API lifecycle before deployment.
  • Development (Jump To) (Presentation) - Understanding the many ways in which APIs can be deployed.
  • Production (Jump To) (Presentation) - Thinking critically about properly operating API infrastructure.
  • Governance (Jump To) (Presentation) - Understanding how to measure, report, and evolve API operations.

Not all workshops will cover all of these areas. Depending on the time available, the scope of the team participating in a workshop(s), and how far along teams are in their overall API journey, the workshops might head in different directions, and expand or contract the depth in which we dive into each of these area (ie. not everyone is ready for governance). After several workshops this year, we have found these areas of the API lifecycle to be the most meaningful ways to organize a workshop, and help enterprise group think more critically about their API strategy.

Craft An API Strategy For Your Enterprise

The purpose of this API lifecycle workshops is to help enterprise organizations develop their own API strategy. Bring in outside API knowledge, learn more about where an enterprise API group is in their overall API journey, and leave them with a structured artifact that helps them step back and look at the entire lifecycle of their APIs. Moving the API conversation across the enterprise forward in a meaningful way with three distinct actions:

  • Jumpstart Your API Lifecycle Strategy - This workshop starts with this template API lifecycle strategy in GitHub or GitLab as README, and YAML file. Standing up a framework to consider as you craft your own API strategy, providing a starting point for your journey. Generated from eight years of research on the API space, providing a living document that can be used to execute and evolve the overall API lifecycle strategy for an enterprise organization.
  • API Lifecycle Workshop - Conduct a single, or multi-day API lifecycle workshop on-site, with as many enterprise and / or partner stakeholders as possible. We will come on site, and walk teams through each stop along a modern API lifecycle, helping customize, personalize, and make the API strategy better fit the enterprises strategy.
  • Evolve Your API Lifecycle Strategy - Coming out of the workshop, you will be given an updated API lifecycle artificat file in YAML, with an outline, and presentation to help navigate. Providing a human and machine readable framework that represents your API lifecycle strategy, helping provide a scaffolding for future discussions. Producing a usable artifact out of the gathering, encapsulating the research and experience we bring to the table, adding what we learned during the workshop, and hopefully continually being used to drive the API strategy road map.
  • Continue Answering Your Questions - After the workshop is done, and we have an updated API lifecycle, we are here to support. We can answer questions via the repository we leave an API strategy artifact, as well as email. We are happy to conduct virtual meetings to help check in on where you are at, and of course we are happy to always come back and conduct future workshops as you need.

I am happy to continue the conversation around the API lifecycle artifact we will leave with you. I don’t expect you to use everything we propose. I more more interested in teaching you about what is possible, and continuing to work with you to refine, evolve, and make the API lifecycle your own. We’ve just worked hard to identified many different ways to operating API infrastructure at scale, and continue to help standardize and make it more accessible by large enterprise organizations.

Helping You In Your Journey

Ultimately, the API lifecycle strategy we will leave behind, possesses all the knowledge we’ve aggregated across our API research, gathered across leading API providers, and honed by conducting API workshops within enterprise groups. Embedded within this API lifecycle artifact we’ll leave you with some added elements that will help you in your journey, going beyond just advice on process, and helping the rubber meet the road.

  • Links - Provide a wealth of references to external resources, attached to each stop along the API lifecycle, bring our API research into your organization, allowing you to put to use inline as you are building your API strategy.
  • Services - Embedding links to API services that you are already using, and introducing you to other useful API services along the way. Making sure specific services are associated with each stop along the API lifecycle, across the different areas, and even sub-linking to specific features that can help accomplish a specific aspect of API operations.
  • Tooling - Embedding links to open source API tools, specifications, and other solutions that can be used to accomplish a specific aspect of operating an API platform. Brining in open source solutions that can be considered as you are crafting the API strategy for your enterprise organization.

While not all organizations will be ready to use a YAML API lifecycle artifact as part of their API orchestration, it helps to have the API lifecycle well defined, even if many steps are still manual. It helps teams think more critically about how they approach the deliver of APIs, while also being something that can be downloaded, forked, and reused by different groups across the enterprise. Eventually it is something that can be further automated, measured, and used to help quantify the maturity level of each APIs, as well as API across distributed teams.

Let's begin this lifecycle journey with a look at API discovery...

API Discovery (Presentation)

Ensuring APIs are known across all teams, across the entire organization, and are always actively maintained.

  • Low Hanging Fruit (outline) - Understanding what resources are already on the public websites, and applications, by spidering existing domains looking for data assets that should be delivered as API resources.
  • Discovery (outline) - Actively looking for web services and APIs that exist across an organization, industry, or any other defined landscape. Documenting, aggregating, and evolving what is available about each API, while also publishing back out and making available relevant teams.
  • Communication (outline) - Having a strategy for reaching out to teams and engaging with them around API discovery, helping them remember to register and define their APIs as part of wider strategy.
  • Definition (outline) - Work to ensure that all definitions are being aggregated as part of the process so that they can be evolved and moved forward into design, development and production--investing in all of the artifacts that will be needed down the road.
  • Dependencies (outline) - Defining any dependencies that are in play, and will play a role in operations. Auditing the stack behind any service as it is being discovered and documented as part of the overall effort.
  • Support (outline) - Ensure that all teams have support when it comes to questions about web service and API discovery, helping them initially, as well as along the way, making sure all their APIs are accounted for, and indexed as part of discovery efforts.

API Design (Presentation)

Defining and designing API contracts that can be used across develop, production, and governance areas of the lifecycle.

  • Definition (outline) - Using definitions as the center of the API design process, developing an OpenAPI contract for moving things through the design phase, iterating, evolving, and making sure the definitions drive the business goals behind each service.
  • Design (outline) - Considering the overall approach to design for all APIs, executing upon design patterns that are in use to consistently deliver services across teams. Leveraging a common set of patterns that can be used across services, beginning with REST, but also eventually allowing the leveraging of hypermedia, GraphQL, and other patterns when it comes to the deliver of services.
  • Versioning (outline) - Managing the definition of each API contract being defined as part of the API design stop for this area of the lifecycle, and having a coherent approach to laying out next steps.
  • Virtualization (outline) - Providing mocked, sandbox, and virtualized instances of APIs and other data for understanding what an API does, helping provide an instance of an API that reflects exactly how it should behave in a production environment.
  • Testing (outline) - Going beyond just testing, and making sure that a service is being tested at a granular level, using schema for validation, and making sure each service is doing exactly what it should, and nothing more.
  • Landing Page (outline) - Making sure that each individual service being designed has a landing page for accessing it's documentation, and other elements during the design phase.
  • Documentation (outline) - Ensuring that there is always comprehensive, up to date, and if possible interactive API documentation available for all APIs being designed, allowing all stakeholders to easily understand what an API is going to accomplish.
  • Support (outline) - Ensuring there are support channels available for an API, and stakeholders know who to contact when providing feedback and answering questions in real, or near real time, pushing forward the design process.
  • Communication (outline) - Making sure there is a communication strategy for moving an API through the design phase, and making sure stakeholders are engaged as part of the process, with regular updates about what is happening.
  • Road Map (outline) - Providing a list of what is being worked on with each service being designed, and pushed forward, providing a common list for everyone involved to work from.
  • Discovery (outline) - Make sure all APIs are discoverable after they go through the design phase, ensuring each type of API definition is up to date, and catalogs are updated as part of the process.

API Development (Presentation)

Understanding the actual development and delivery of API resources, based upon API contracts defined during design phase.

  • Definition (outline) - Using definitions to guide the development process, making sure the API contract is used to drive th development of code, and moving it from development to QA, and into production.
  • Discovery (outline) - Making sure there are machine readable definitions available at development time, providing an OpenAPI as a contract for what each service should do.
  • Virtualization (outline) - Continuing to maintain virtualized instances of APIs as part of the API development process.
  • Database (outline) - Defining the database layer behind each service, providing an isolated database for the access and storage of all data used as part of each service.
  • Storage (outline) - Defining the storage layer that is used as part of a services operation, providing a single strategy for managing the storage of objects used by each service.
  • DNS (outline) - Managing the DNS for a service, ensuring it is part of a wider DNS strategy, and allows for isolation of each service within a specific domain namespace.
  • Deployment (outline) - Managing the actual deployment of an API into product, providing a common way in which APIs are deployed. Defining one, or many ways in which APIs can be put into production as part of any service.
  • Orchestration (outline) - The orchestration of the build and deliver of a service, defining how the technical building blocks are orchestrated to deliver the resulting service.
  • Dependencies (outline) - Defining the dependencies associated with each service, helping quantifying what each service needs to do what it does successfully.
  • Testing (outline) - Going beyond just testing, and making sure that a service is being tested at a granular level, using schema for validation, and making sure each service is doing exactly what it should, and nothing more.
  • Performance (outline) - Establishing what the benchmarks are for a service, and what can be expected when it comes to performance.
  • Security (outline) - Going beyond authentication, encryption and other aspects of security, and working to scan the surface area of APIs to ensure that there are no vulnerabilities, and that APIs are not doing anything they should not be doing. Keeping services secure, and operating reliably.
  • Communication (outline) - Having a comprehensive communication strategy for a service, ensuring that each service is properly communicating with other teams, stakeholders, and API consumers. Providing a regular stream of information regarding what is happening with the service.
  • Support (outline) - Ensuring that each individual API has the necessary support, making sure that the support channels for a service are easy to find, have a responsive and knowledgeable person available to answer questions, and is being measured and audited for quality.

API Production (Presentation)

Moving to and operating APIs in production, and making sure services are consistently delivered across the organization.

  • Definition (outline) - All of the definitions that go into defining each service, from the original schema, the OpenAPI definitions, the Postman Collections, and the assertions that contribute to the testing of the service to ensure it is doing what is expected of it.
  • Discovery (outline) - Making sure that all APIs are discoverable by default, and able to be easily registered in API catalogs, and able to be included in search indexes, and API discovery services. Baking API discovery into the regular operations of each service being deployed.
  • Virtualization (outline) - Providing mocked, sandbox, and virtualized instances of APIs and other data for understanding what an API does.
  • Authentication (outline) - Providing a standardized approach to authenticating with the service, allowing consumers to successfully, and securely access a service.
  • Management (outline) - Having a consistent management layer for use across all APIs, applying a strategy for authentication, service composition, logging, analysis, and measuring value being generated at the gateway and management layers.
  • Logging (outline) - Having a consistent strategy for logging across the entire API stack, ensuring that logging is a first class citizen, and all activity across APIs is being stored, shipped, and made accessible across analysis systems and tooling.
  • Budgets (outline) - Understanding what the costs associated with API development and operation are, tracking all the costs along the way so it can be used to help understand the value being generated, and drive the overall plan for operating a service.
  • Plans (outline) - Having one or many plans for accessing each service, ensuring that all consumption occurs through the filter of a plan, and fit into a wider platform management strategy.
  • Portal / Landing Page (outline) - Providing one, or many public or private portals, providing a single known location for API providers and API consumers to find what they are looking for when it comes to API integration with services being made available.
  • Getting Started (outline) - Providing basic getting started information for developers to use when on-boarding.
  • Documentation (outline) - Ensuring that there is always comprehensive, up to date, and if possible interactive API documentation available for all APIs, providing developers with everything they need to understand what an API does, and successfully integrate APIs into their applications.
  • Code (outline) - Providing code samples, libraries, SDKs, and other solutions in a variety of languages, and for a variety of platforms, helping do much of the heavy lifting that is required when it comes to putting an API to use in applications, and system to system integration.
  • Licensing (outline) - Ensuring that all of the licensing for the entire API stack has been considered, providing references for the licenses of each layer of API operations, and even dependencies whenever possible.
  • Support (outline) - Ensuring that each individual API has the necessary support, making sure that the support channels for a service are easy to find, have a responsive and knowledgeable person available to answer questions, and is being measured and audited for quality.
  • FAQs (outline) - Providing a self-service listing of the most common questions that get asked of a service, so that API consumers will to have to ask the question, and put support channels to work, resulting in additional resources being required to support the platform.
  • Communication (outline) - Having a comprehensive communication strategy for a service, ensuring that each service is properly communicating with other teams, stakeholders, and API consumers. Providing a regular stream of information regarding what is happening with the service.
  • Road Map (outline) - Providing API consumers with as much information as possible about what changes are being planned for a service. Helping include consumers in the conversation about what is being planned whenever possible.
  • Issues (outline) - Being transparent around the issues that are currently outstanding regarding a platform. Potentially saving resources having to respond to further emails, tickets, and issues being reported.
  • Change Log (outline) - Provide consumers with a detail history of what has changed in the past with a service. Rolling over road map items, and issues when they have been accomplished or satisfied into a detailed change log.
  • Legal (outline) - Covering the legal bases when it comes to operating a service, ensuring there are terms of service, privacy policies, and the other legal aspects of delivering a service online, with partners, and even internally with an organization.
  • Monitoring (outline) - Making sure all aspects of a service is being monitored, understanding the overall availability of a service, and whether or not a service is being delivered as expected, and meeting the SLA as promised.
  • Testing (outline) - Going beyond just testing, and making sure that a service is being tested at a granular level, using schema for validation, and making sure each service is doing exactly what it should, and nothing more.
  • Performance (outline) - Testing each service for performance, benchmarking the speed in which resources are being delivered from multiple regions, working to understand and establish what the baseline speed for each API is, and understanding if the service is meeting, or falling beneath expectations.
  • Security (outline) - Going beyond authentication, encryption and other aspects of security, and working to scan the surface area of APIs to ensure that there are no vulnerabilities, and that APIs are not doing anything they should not be doing. Keeping services secure, and operating reliably.
  • Analysis (outline) - Measuring, quantifying, and analyzing the usage of all APIs to make sure the platform is aware of how all APIs are being put to to use, and that teams are able to respond to any type of activity on the platform in near real time.
  • Stages (outline) - Understanding what the stages are for each service, defining the overall maturity of each service, and understanding the road from inception to production.
  • Maintenance (outline) - Defining what maintenance looks like for each service, defining what is needed to keep a service running, and meeting the recurring needs of each API being made available.

API Governance (Presentation)

Getting more organized about how APIs are quantified, understood, and reported upon across the entire organization.

  • Structure (outline) - Working to understand the scope and structure for governance operations, establish the right approach to understanding API operations across an organization, and be effective when working with many different teams, operating at different levels of maturity.
  • Design (outline) - Work to provide guidance regarding API design, and consider how to measure if it is being implemented by teams. Working from group level, or centralized API guidance, and working to refine regularly across teams as things change.
  • Testing (outline) - Work to provide guidance regarding API testing, and track on the results of testing from design to production, making sure the entire history of a service exists, and the overall health of the APIs is fully understood.
  • Monitoring (outline) - Work to provide guidance regarding API monitoring, and track on the results of testing from design to production, making sure the entire history of a service exists, and the overall availability of the APIs is fully understood--meeting all SLAs.
  • Performance (outline) - Work to provide guidance regarding API performance, and understand how well APIs perform from different regions and cloud platforms. Providing a clear picture on what levels of performance each API will be able to achieve as part of overall service level agreements.
  • Security (outline) - Work to provide guidance regarding API security, scanning the entire surface area of an API on a regular basis looking for vulnerabilities, and anything that might be exploited by bad actors.
  • Observability (outline) - Push for observability into all teams and the services that they operate, making sure every stop along an API lifecycle is accessible to the entire team, with an emphasis on automation, and streamlining how each system understood.
  • Discovery (outline) - Ensuring that all APis are discoverable and able to be measured as part of overall governance. If it isn't known about it can't be monitored, tested, secured, and analyzed for the value it generates across an organization.
  • Analysis (outline) - Measuring as much as possibly regarding what is going on with API activity, and centrally aggregating it to be analyzed for how API operations can be improved upon. Making sure everything that is being measured is also being analyzed, otherwise it shouldn't be collected in the first place.

Navigating This Workshop

This workshop centers around a single mock API, and is driven by a central YAML definition which provides a human and machine readable API lifecycle outline. This YAML definition drives the outline of lifecycle stops present on this page, as well as items for each stop, and the other details provided. Providing several core elements for exploring, learning about, and hopefully evolving this API lifecycle blueprint to be your own. There are X core building blocks of this blueprint:

  • API Developer Portal (view) - A working developer portal to show what is possible.
  • API Lifecycle Presentation(s)
    • Discovery - A walk through of the discovery phase.
    • Design - A walk through of the design phase.
    • Development - A walk through of the development phase.
    • Production - A walk through of the production phase.
    • Governance - A walk through of the governance layer.
  • API Lifecycle Config (view) - The YAML API lifecycle checklist for the locations API.
  • API Lifecycle Checklist (view) - A simple checklist of all the stops and items to consider on the checklist.

This lifecycle can be applied to a single API, or many APIs as part of a more holistic strategy. While many stops along this API lifecycle will be manual to begin with, because it exists as a YAML artificact, it introduces the opportunity to think about automation at every stop. Providing a human and machine readable API lifecycle document, that can be used for outlines, presentations, documentation, and eventually driving the API delivery pipeline across an organization.