API Discovery

Ensuring APIs are known across teams.

Low Hanging Fruit

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.

  • Spreadsheets (details) - Identify all of the XML files that are published across any domains.
  • CSV (details) - Identify all of the CSV files that have been published within any domains.
  • XML (details) - Identify all of the XML files that have been published within any domains.
  • JSON (details) - Identify all of the JSON files that have been published within any domains.
  • Tables (details) - Identify all of the HTML tables that have been published within any domains.

Discovery

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.

  • WSDL (details) - Looking for WSDL documents across an organization.
  • API.json (details) - Looking for APIs.json files across an organization.
  • OpenAPI (details) - Looking for OpenAPI files across an organization.
  • Postman Collection (details) - Looking for Postman Collections across an organization.
  • HTML (details) - Looking for HTML service and API documents across an organization.
  • .HAR (details) - Looking for evidence of APIs from .HAR files tht are gathered.
  • Logs (details) - Looking for evidence of APIs from log files tht are gathered.

Communication

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.

  • Email (details) - Use email to coordinate with other groups.
  • Meetings (details) - Having regular meetings to discuss where APIs are.
  • Workshops (details) - Conducting workshops to actively develop wider discovery practices.

Definition

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.

  • Organization (details) - Defining the organizational structure, group, or other bounded context for organization definitions into.
  • Schema (details) - Organizing individual schema assocated with a service, while also including it as part of the OpenAPI.
  • OpenAPI (details) - Producing an OpenAPI should be the central objective of the API discovery process, producing, then also evolving each API's definition throughout the lifecycle.
  • Domain (details) - Considering the domain that services fits into and exploring the sphere of knowledge and activity around the domain each service is delivering value within. Quantifying the service domain, helping decompose from a larger domain, and helping focus what each service does.
  • Event Storming (details) - Event storming is a rapid, lightweight, and underappreciated group modeling technique that is intense, fun, and useful for accelerating development teams.
  • Vocabulary (details) - Organizing the common vocabulary in use across services, and APIs, establishing a single place to find the language used across domains.
  • Tags (details) - Defining what the tagging taxonomy will be for applying across resources, for use in tagging across definitions, documentation, and infrastructure operations.
  • Team(s) (details) - Map out all of the individuals being engaged as part of the service and API discovery process, and grouping them by team, group, or other organizational structure.
  • Catalog (details) - Establish a central way to track on all API definitions that are being organized, from a folder on network drive, to GitHub, GitLab, or other CMS, with the object to eventually publish all usable definitions to a master catalog.

Dependencies

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.

  • Services (details) - What existing services does a service depend on to do what it does, and would be impacted if something changes.
  • Software (details) - What are the software libraries a service depends on for its operations, covering the code layer dependencies.
  • Data (details) - What is the provenance of data being used as part of the service, and where are their continued dependencies.
  • People (details) - What people is a service dependent on, requiring coordination, communication, and effort from individuals to move forward, and ensuring the right stakeholders are involved.
  • Organizations (details) - What other organizations, internally or externally are required to move a service forward, making sure all stakeholders are considered.
  • Applications (details) - Documenting the client applications depeendencies for a service, outlining who depends on the service based upon the applications they are using.

Support

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.

  • Email (details) - The email account for supporting each service.
  • GitHub Issues (details) - Where to submit an issue to get support for each service.

API Design

Defining and designing API contracts.

Definition

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.

  • Organization (details) - The over-arching source control organization for each service, providing an umbrella for different development groups and projects, and governing who has accesss to each design.
  • Repository (details) - Leveeraging source control repository for each service, providing a self-contained, shareable, forkable way to engage with a service. Allowing for EVERYTHING involved with a service to be accessed in a single location.
  • README (details) - The README for each services repository, providing an overview of the service, complete with all the relevant links to all the moving parts. Any user should be able to land on the README, and easily get up to speed on what a service delivers.
  • Service Name (details) - A simple title for each service, describing what it does in concise terms, providing a simple way for any internal or external part to learn about the value it offers.
  • Service Description (details) - A simple, descriptive paragraph for each service. Providing less that 250 words about what value each service delivers. Avoid just writing the obvious, and describing what an APIs, and focusing in on describing the value being delivered by each service.
  • Schema (details) - JSON schema for the data behind service, providing a stanalone JSON schema for use in other systems, applications, and services. Doing the heavy lifting of describing the objects, fields, types, and other technical details of the data behind each service.
  • OpenAPI (details) - An OpenAPI definition for the surface area of the API, providing a machine readable contract for what each service delivers, that can be used across the API lifecycle, guiding everying aspect of delivering each service.
  • Domain (details) - Considering the domain that each service fits into and exploring the sphere of knowledge and activity around the domain each service is delivering value within, ensuring the the right definitions, vocabulary, and other elements are present at design time.
  • Tags (details) - Defining what the tagging taxonomy will be for applying across resources, for use in tagging across definitions, documentation, and infrastructure operations. Ensuring that APIs leave this stage of the lifecycle properly tagged for organization, indexing and discovery.
  • Assertions (details) - Human and machine readable assertions of what service does, leveraging the existing JSON schema, and translating that into business objectives, asserting that a service does what it is supposed to--providing a simple bulleted list explaining what is expected of a service.
  • Scenarios (details) - Providing machine readable definitions that provide the mappings and business rules for orchestrations, scenarios, and other automated processes associated with a service, for use as part of testing, monitoring, security, and other automated functionality.
  • Team (details) - A list of team members for the service, providing a nice list of who is responsible for designing the relevant business contract that will be needed to move a service from design to production.
  • Export Contract (details) - Ensuring that all contracts and artifacts are exported as part of the design area of the lifecycle, making it available for use across development and production stages.

Design

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.

  • Base Path (details) - Defining the part of the API path that goes after the host, and before each path, and is constant across all endpoints for each service.
  • Path(s) (details) - The paths that are used to define each individual API resource, providing a plain language descrption of a resource, with a meaningful, logical, structured path for accessing each individual resource.
  • Verb(s) (details) - The HTTP verbs used for each service, including GET, POST, PUT, and DELETE, but also leverage other HTTP verbs when relevant.
  • Parameters (details) - The query parameters that are used by each service, as described by the OpenAPI. Providing a list of parameters that can be used to define the API request dimensions that are available for a service.
  • Headers (details) - Logically using HTTP headers by each service, as described by the OpenAPI, properly leveraging the web when it comes to the transport of all resources.
  • Body (details) - Usage of the body as part of API requests as opposed to parameters, or in parallel to. Is the body used for POST, PUT, and other variations to help manage the payload.
  • Beyond Verbs With Actions (details) - Consistently defining how actions will be designed beyond the usage of the common HTTP verbs, having a set of design patterns for addressing actions made across all resources.
  • Media Types (details) - Quantifying the media types that are used by each service, as described by the OpenAPI. Providing multiple representations of a resource, allowing consumer to negotiate the type of content.
  • Hypermedia (details) - Emulating the patterns present in the web, and leverage existing hypermedia types to make APIs more resilient, evolvable, and flexible when it comes to client integration.
  • Status Codes (details) - Defining the HTTP status codes that are used by each service, as described by the OpenAPI. Leveraging the web to help understand what a service is doing at scale, as part of automated integration and consumption of a service.
  • Filtering (details) - Allowing for the filtering of data returned as part of responses, leveraging paths, parameters, and other API building blocks to filter the responses a consumer will actually see.
  • Pagination (details) - Defining the pagination used by each service, providing the ability to break large responses down into smaller more manageable chunks across al resources in a consistent way by clients.
  • Sorting (details) - The sorting used by each service, allowing consumers to sort the responses they see and define what the order of data will be when consuming API resources.
  • Response(s) (details) - The responses that are used by each service, as described by the OpenAPI. Providing details regarding the response, and referencing the schema being returned as part of the response.
  • Errors (details) - Defining a structure for error handling that leverages HTTP status codes, but goes further with a common schema definition.

Versioning

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.

  • Major (details) - Define the major release for each service.
  • Minor (details) - Define the minor release for each service.
  • Road Map (details) - Making sure there is a road map definition for each version of a service.
  • Communication (details) - Ensuring there is a strategy for communicating with all stakeholders around the release.

Virtualization

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.

  • Paths (details) - Considering offering mock API paths for use by integrators, providing production-like instances of the API to use, and play with to provide feedback on API services.
  • Data (details) - Considering offering synethic data for use by integrators, helping ensure virtualized APIs provide as production like experience in a virtualized way.

Testing

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.

  • Scenarios (details) - The sceanrios for testing each service.
  • Saved Requests (details) - Save specific requests from a service to be used in testing.
  • Responses (details) - Save specific responses from a service to be used in testing.
  • Playback (details) - Allowing requests to be played back, based upon history.
  • Results Archive (details) - The results of assertions tested against each service, providing a history of all tests.
  • Reporting (details) - Having a strategy for reporting from testing that is occuring.

Landing Page

Making sure that each individual service being designed has a landing page for acccessing it's documentation, and other elements during the design phase.

  • Hosting (details) - Information about the hosting service used for this portal.
  • Template (details) - Information regarding the UI template used for this portal.
  • Discovery (details) - Ensure that each services landing page is discoverable through the design phase.

Documentation

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.

  • Paths (details) - Documentng the API paths that are available for each service.
  • Schema (details) - The descriptive header and footer paragraphs for the documentation schema.
  • Examples (details) - Examples of using the API path for each service.
  • Definitions (details) - Links to the machine reaable API definitions for use as part of each service.
  • Errors (details) - Details about the errors encountered using each service, including status codes, and messages.

Support

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.

  • Email (details) - The email account(s) for supporting each service.
  • GitHub Issues (details) - Where to submit an issue to get support for each service.
  • Tickets (details) - Providing a ticketing system for submitting formal support requests as part of the design process.

Communication

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.

  • Blog (details) - The blog for each service.
  • Github (details) - The Github account for each service.
  • Internal (details) - Internal communication channel for each service, like Slack or other channel.
  • External (details) - External communication channels for each service, like Slack or other channel.
  • Workshops (details) - Conducting workshops to actively develop wider design practices.

Road Map

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.

  • Private (details) - Providing an internal, private road map that design stakeholders can use to understand what is being designed.
  • Public (details) - Providing an puling road map (when applicable) that design stakeholders can use to understand what is being designed.
  • Suggest (details) - Provide a mechanism for users to make suggestions for the road map.

Discovery

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.json (details) - Publish an API discovery document for indexing API operations.
  • OpenAPI (details) - Provide an OpenAPI definition for each individual service.
  • Postman Collection (details) - The Postman Collection for each individual service.
  • Catalog (details) - Keeping all definitions available in a central catalog after design time.

API Development

The actual development and delivery.

Definition

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.

  • Repository (details) - Use repository to version, build, and deploy each service.
  • README (details) - Update the README for the repository to reflect what is happening as part of development.
  • Schema (details) - JSON schema for the data behind service, providing a stanalone JSON schema for use in other systems, applications, and services. Doing the heavy lifting of describing the objects, fields, types, and other technical details of the data behind each service.
  • OpenAPI (details) - An OpenAPI definition for the surface area of the API, providing a machine readable contract for what each service delivers, that can be used across the API lifecycle, guiding everying aspect of delivering each service.
  • Team (details) - Extend the team list for a service to include the development, QA, and other stakeholders involved in this area of the lifecycle.

Discovery

Making sure there are machine readable definitions available at development time, providing an OpenAPI as a contract for what each service should do.

  • API.json (details) - The API discovery document for each service.
  • OpenAPI (details) - The complete OpenAPI for each service.
  • Postman Collection (details) - The Postman Collection for each service.

Virtualization

Continuing to maintain virtualized instances of APIs as part of the API development process.

  • Paths (details) - Offering mock API paths for use by developers to understand what an API does / should do.
  • Data (details) - Considering offering synethic data for use by integrators, helping ensure virtualized APIs provide as production like experience in a virtualized way.

Database

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.

  • Platform (details) - The database platform used to drive each service, providing a dedicated database to just drive each service.
  • Schema (details) - Making sure there is a database version of the schema, providing a raw dump and backup of the database behind each service.
  • Region (details) - Where the database for each service is located, helping articulate if there is replication, or regional specific implementations or considerations for each service.
  • Access (details) - How the database is connected with by the service, defining what connectivity is required, and what dependencies are involved with access.
  • Logs (details) - Understanding how logging occurs for the database, what is turned on, and where logs are stored, and or shipped to as part of regular operations.
  • Backup (details) - Ensuring that the database has a backup strategy, and the details of what is backed up and how long it is being backed up.
  • Encryption (details) - Ensuring the encryption is part of the database operations, making sure data is being stored as part of the database behind each service.

Storage

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.

  • Platform (details) - The platform that is used for storage behind each service.
  • Region (details) - Where the storage is located that is used for each service.
  • Access (details) - Details on how storage is accessed as part of each service.
  • Logs (details) - Information about the logging for storage behind service.
  • Backup (details) - Ensuring there is a backup strategy for storage behind service.
  • Encryption (details) - Ensuring encryption is considered for storage.

DNS

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.

  • Platform (details) - Which platform is used to provide DNS for service.
  • Mock (details) - The host used for the mock API.
  • Development (details) - The host used for the development API, providing access to the version of API currently being developed.
  • Production (details) - The host used for the production API, which is the address that should actually be used in applications.
  • Portal (details) - The host used for the developer portal, providing a single location that everyone can find what is happening around a service.
  • Encryption (details) - Ensuring encryption is used as part of API transport, and SSL is default for all services.

Deployment

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.

  • Compute (details) - The compute that is delivering each service.
  • Framework (details) - Which programming framework is used to deploy each service.
  • Function (details) - Which function is used to deploy each service.
  • Containers (details) - Which container is used to deploy each service.
  • Gateway (details) - Which gateway is used to deploy each service.
  • Pipeline (details) - Information regarding the pipeline in use for service.
  • Region (details) - Information regarding which region each service is deployed.

Orchestration

The orchestration of the build and deliver of a service, defining how the technical building blocks are orchestrated to deliver the resulting service.

  • Build (details) - Information regarding the build of each service and how it is deployed.
  • Hooks (details) - Information regarding pre or post commit hooks for each service.
  • Jobs (details) - Information regarding the jobs used as part of each service.
  • Events (details) - Information about events used for managing jobs for each service.
  • Schedule (details) - Information about the schedule sin use to manage each service.

Dependencies

Defining the dependencies associated with each service, helping quantifying what each service needs to do what it does successfully.

  • Service (details) - Information about services each service depends on.
  • Software (details) - Information about software each service depends on.
  • Data (details) - Information about data each service depends on.
  • People (details) - Information about people each service depends on.
  • Organization (details) - Information about organization each service depends on.
  • Applications (details) - Information about applications that depend on services.

Testing

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.

  • Scenarios (details) - The sceanrios for testing each service.
  • Saved Requests (details) - Save specific requests from a service to be used in testing.
  • Results (details) - The results of assertions tested against each service.

Performance

Establishing what the benchmarks are for a service, and what can be expected when it comes to performance.

  • Tests (details) - The performance tests for each service.
  • Results (details) - The results of performance test for each service.

Security

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.

  • Overview (details) - The overview of security practices for each service.
  • Policies (details) - The policies in use for each service.
  • Tests (details) - The security tests in use for each service.
  • Results (details) - The results of security for each service.

Communication

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.

  • Blog (details) - The blog for each service.
  • Twitter (details) - The Twitter account for each service.
  • Github (details) - The Github account for each service.
  • Internal (details) - Internal communication channel for each service.
  • External (details) - External communication channels for each service.
  • Workshops (details) - Conducting workshops to actively develop wider development practices.

Support

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.

  • Email (details) - The email account for supporting each service.
  • GitHub Issues (details) - Where to submit an issue to get support for each service.
  • Twitter (details) - Where to get support publicly using a supported Twitter account
  • Ticket (details) - Where to submit a ticket to get support for each service.

API Production

Moving to and operating APIs in production.

Definition

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.

  • Organization (details) - The over-arching source control organization for each service, providing an umbrella for different development groups and projects.
  • Repository (details) - The source control repository for each service, providing a self-contained, shareable, forkable way to engage with a service. Allowing for EVERYTHING involved with a service to be accessed in a single location.
  • README (details) - The README for each services repository, providing an overview of the service, complete with all the relevant links to all the moving parts. Any user should be able to land on the README, and easily get up to speed on what a service delivers.
  • OpenAPI (details) - An OpenAPI definition for the surface area of the API, providing a machine readable contract for what each service delivers, that can be used across the API lifecycle, guiding everying aspect of delivering each service.
  • Tags (details) - Using the common tags and taxonomy for operating infrastructure and other resources, allowing for easy discovery, measurement and reporting of what it taks to operate each service.
  • Team (details) - A list of team members for the service, providing a nice list of who is responsible for making a service operate, defining who ultimately owns and sustains each service.

Discovery

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.

  • API.json (details) - The API discovery document for each service.
  • OpenAPI (details) - The complete OpenAPI for each service.
  • Postman Collection (details) - The Postman Collection for each service.
  • Catalog (details) - Leverage the service catalog as part of operations, ensuring that the definitions for each service are used to govern operations.

Virtualization

Providing mocked, sandbox, and virtualized instances of APIs and other data for understanding what an API does.

  • Paths (details) - Considering offering mock API paths for use by integrators, providing production-like instances of the API to use, and play with to provide feedback on API services.
  • Data (details) - Considering offering synethic data for use by integrators, helping ensure virtualized APIs provide as production like experience in a virtualized way.

Authentication

Providing a standardized approach to authenticating with the service, allowing consumers to successfuly, and securely access a service.

  • Type (details) - Information about the types of authentication that are available for each service, following the common authentication strategy.
  • Overview (details) - An overview for the authentication of each service, helping users understand how they will access a service.
  • Signup / Login (details) - An overview for the authentication of each service.

Management

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.

  • Platform (details) - Details on which API management platform is used for each service.
  • Administration (details) - Where you find the administrative access for API management.
  • Signup (details) - Where you can sign up for access to each service.
  • Login (details) - Where you can login for access to each service.
  • Account (details) - Where you can access accouint information when using service.
  • Applications (details) - Details about the developer's applications approved to use each service.

Logging

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.

  • Database (details) - Information about database logs.
  • API (details) - Information about API logs.
  • DNS (details) - Information about DNS logs.
  • Shipping (details) - Information about shipping logs centrally to service's storage.

Budgets

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.

  • Acquisition (details) - Understanding what it costs to acquire the resources behind each service.
  • Development (details) - Understanding what it cost to develop each service.
  • Operation (details) - Understanding what it costs to operate each service.
  • Value (details) - Articulating what value is provided by each service.

Plans

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.

  • Tiers (details) - The tiers of access for each service.

Portal / Landing Page

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.

  • Hosting (details) - Information about the hosting service used for this portal.
  • Template (details) - Information regarding the UI template used for this portal.
  • Analytics (details) - Information about the analytics in use for tracking on this portal.

Getting Started

Providing basic getting started information for dvelopers to use when on-boarding.

  • Signup (details) - Where you can signup for each service.
  • Authentication (details) - Where you can get details about authenticating with each service.
  • Documentation (details) - Where you can find documentation for each service.
  • SDKs (details) - Where you can find SDKs in multiple programming languages for each service.
  • FAQ (details) - Where you can get your common questions answered around each service.
  • Support (details) - Where you can get support for using each service.

Documentation

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.

  • Paths (details) - Documentng the API paths that are available for each service.
  • Schema (details) - The descriptive header and footer paragraphs for the documentation schema.
  • Examples (details) - Examples of using the API paths for each service.
  • Definitions (details) - The machine reaable API definitions for use as part of each service.
  • Errors (details) - Details about the errors encountered using each service.

Code

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.

  • PHP (details) - This is the PHP SDK for integrating with each service.
  • Python (details) - This is the Python SDK for integrating with each service.
  • Ruby (details) - This is the Ruby SDK for integrating with each service.
  • Go (details) - This is the Go SDK for integrating with each service.
  • Java (details) - This is the Java SDK for integrating with each service.
  • C# (details) - This is the C# SDK for integrating with each service.
  • Node.js (details) - This is the Node.js SDK for integrating with each service.
  • JavaScript (details) - This is the JavaScript SDK for integrating with each service.

Licensing

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.

  • Server (details) - The licensing for the server code behind each service.
  • Data (details) - Licensing for the data used as part of each service.
  • API (details) - Licensing for the API interface for each service.
  • SDKs (details) - Licensing for the SDKs provided for each service.

Support

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.

  • Email (details) - The email account for supporting each service.
  • GitHub Issues (details) - Where to submit an issue to get support for each service.
  • Twitter (details) - Where to get support publicly using a supported Twitter account
  • Ticket (details) - Where to submit a ticket to get support for each service.

FAQs

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.

  • Categories (details) - The categories of FAQ questions.
  • Questions (details) - The questions asked about each service.
  • Ask Question (details) - Asking a question about each service.

Communication

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.

  • Blog (details) - The blog for each service.
  • Twitter (details) - The Twitter account for each service.
  • Github (details) - The Github account for each service.
  • Internal (details) - Internal communication channel for each service.
  • External (details) - External communication channels for each service.
  • Workshops (details) - Conducting workshops to actively develop wider production practices.

Road Map

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.

  • Private (details) - Where you can access the private road map for each service.
  • Public (details) - Where you can access the public road map for each service.
  • Suggest (details) - Consumers are welcome to suggest an addition to the road map.

Issues

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.

  • Entries (details) - Listing of all the outstanding issues for each service.
  • Report (details) - Reporting an issue for each service.

Change Log

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.

  • Entries (details) - Providing a list of what has changed with this platform along with each road map item being accomplished, and issue being resolved.

Legal

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.

  • Terms of Service (details) - The terms of service (TOS) for each service.
  • Privacy Policy (details) - The privacy policy for each service.

Monitoring

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.

  • Monitors (details) - The monitors for each service.
  • Status (details) - The status of each service.

Testing

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.

  • Assertions (details) - The assertions for each service.
  • Results (details) - The results of assertions tested against each service.

Performance

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.

  • Tests (details) - The performance tests for each service.
  • Results (details) - The results of performance test for each service.

Security

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.

  • Overview (details) - The overview of security practices for each service.
  • Policies (details) - The policies in use for each service.
  • Tests (details) - The security tests in use for each service.
  • Results (details) - The results of security for each service.

Analysis

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.

  • Web Traffic (details) - The traffic information for each service.
  • API Usage (details) - The usage information for each service.
  • Appliction Usage (details) - The application usage across service.
  • SLA (details) - The service level agreement for each service.
  • Reporting (details) - Making sure that everything is being actively reported upon.

Stages

Understanding what the stages are for each service, defining the overall maturity of each service, and understanding the road from inception to production.

  • Discovery (details) - When things are still being discovered, and figured out for design.
  • Design (details) - When things are still being designed and contract hammered out.
  • Development (details) - When a production instance of service is being developed.
  • Production (details) - When a production instance of service is being operated.
  • Outreach (details) - Managing the outreach internally, externally, and publicly for services.
  • Governance (details) - Applying overall governance to each service, and contributing to bigger picture.

Maintenance

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.

  • Weekly (details) - Provide a list that should be considered weekly.
  • Monthly (details) - Provide a list that should be considered monthly.
  • Releases (details) - Provide a list that should be considered for each release.
  • Governance (details) - Provide an outline of how this outline is measured, reported, and evolved.

API Governance

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

Structure

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.

  • Distribution (details) - How distributed or centralized will API governance be.
  • Resources (details) - Defining the resources that are available to realize governance.

Design

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.

  • Paths (details) - Ensuring there are consistently designed API paths.
  • Parameters (details) - Having a common approach to defining parameters.
  • Definitions (details) - Making sure all definitions are properly defined.

Testing

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.

  • Results (details) - Measuring and reporting on all testing results.

Monitoring

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.

  • Results (details) - Measuring and reporting on all testing results.

Performance

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.

  • Results (details) - Measuring and reporting on all testing results.

Security

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.

  • Results (details) - Measuring and reporting on all testing results.

Observability

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.

  • Monitoring (details) - Ensure tessting results are observable.
  • Testing (details) - Ensure tessting results are observable.
  • Performance (details) - Ensure tessting results are observable.
  • Security (details) - Ensure tessting results are observable.

Discovery

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.

  • API.json (details) - Ensure APIs.json are available and measured.
  • OpenAPI (details) - Ensure OpenAPIs are available and measured.

Analysis

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.

  • Traffic (details) - The traffic information across services.
  • Usage (details) - The usage information across services.
  • SLA (details) - The service level agreements across services.
  • Reporting (details) - Making sure that everything is being actively reported upon.