API Discovery

Ensuring APIs are known across teams.

  • 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 the remember to register and define their APIs as part of wider strategy.
  • Definition (outline) - Work to make 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 intially, as well as along the way, making sure all their APIs are accounted for, and indexed as part of discovery efforts.

API Design

Defining and designing API contracts.

  • 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 evetually 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 acccessing 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 is 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

The actual development and delivery.

  • 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 reliabily.
  • 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

Moving to and operating APIs in production.

  • 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 successfuly, 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 proviers 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 dvelopers 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 reliabily.
  • 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

Getting more organized about how API quantified, understood, and reported upon.

  • 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.