What you will learn in Automating API Delivery
APIOps with OpenAPI
Chapter by chapter
Chapter 2: Leaning into APIOps: Problem-solving and leading improvements
What you learn in chapter 2 →Chapter 8: CI/CD for API artifacts 1: Source-stage governance controls
What you learn in chapter 8 →Chapter 9: CI/CD for API artifacts 2: Build-stage and API configuration deployment
What you learn in chapter 9 →Chapter 10: More on API consistency: Custom linting and security checks
What you learn in chapter 10 →Concepts explained in this book
- OpenAPI specificationThe OpenAPI Specification is a standard machine-readable format for describing HTTP APIs, including their operations, inputs, and responses.
- APIOpsThe APIOps Cycles method is a collaborative, lean method for creating API solutions and developing API strategies through eight lifecycle phases.
- api lintingAn API linter is a tool that evaluates API definitions against configurable rules and reports violations.
- review processAn API review process is a defined workflow for evaluating and approving API designs against stated principles, standards, and business needs.
- versioningA version control system is software that records changes to files over time and supports version history, collaboration, and restoration of earlier versions.
- api configurationAn API configuration specifies how external API requests are routed to internal services and which interface constraints and security mechanisms apply.
- deployment pipelineContinuous integration and continuous delivery is a software delivery practice that automates frequent integration, testing, packaging, and deployment.
- SpectralSpectral is an open-source linting tool for validating structured documents, including API descriptions, against configurable rulesets.
- time to first callTime to first transaction is the elapsed time until a user makes their first API call or transaction in a production environment.
- linter ruleA custom linting rule is a user-defined validation rule that specifies where and how an API definition is checked.
- GitOpsGitOps is an operational approach in which version-controlled Git repositories define desired system configuration and automated reconciliation applies it.
- API documentationAPI reference documentation is human-readable documentation generated from an API definition that describes an API's operations, inputs, outputs, and usage contract.
- OpenAPI Generatoropenapi-generator-cli is a command-line Node application that downloads and runs the OpenAPI Generator executable.
- A3 reportA3 problem-solving is a structured scientific method for analyzing improvement problems, planning countermeasures, and communicating progress.
- conversionConversion rate is the percentage of users who complete a defined target action, here making an API call in production after signup.
- retentionUser retention is a measure of the proportion of users who continue to use a product during a specified later period.
- daily active usersDaily active users is the number of unique users who make at least one API call in a production environment during a day.
- time to first hello worldTime to first hello world is the elapsed time required for a developer to achieve a first Hello World result with an API.
- api styleAn API style guide is a documented set of conventions that teams must follow when designing APIs.
- metricA business metric is a quantitative measure of an organization's commercial performance, customer outcomes, quality, or cost.
- lead timeLead time is the elapsed time from when work becomes available to a process step until the completed work becomes available to the next step, including waiting and interruptions.
- schema testA code-based schema test is a schema test implemented as source code that makes assertions about API data against a prescribed schema.
- client libraryA client library is a software library that provides programmatic calls and client-side code for interacting with an API.
- rulesetA ruleset is a collection of validation rules applied together to an API definition.
- api lifecycleAn API life cycle is the sequence of stages through which an API is designed, developed, tested, deployed, operated, improved, and retired.
- gitGit is a distributed version control system for tracking changes to files and coordinating collaborative software development.
- stubA controller stub is generated server-side scaffolding for handling operations exposed by an API controller.
- conformance testingAn API conformance test is an automated verification that an API implementation conforms to its defined API design or OpenAPI definition.
- CI/CD serverA build server is a platform that automates tasks in a software delivery pipeline and coordinates its components.
- API gatewayAn API gateway is a service that acts as a central entry point for API traffic, routing requests to backend services while enforcing cross-cutting policies.
- monitoringMonitoring is the collection and presentation of predefined system measurements with dashboards and alerts to reveal known conditions.
- design-first approachAn API development practice that iteratively creates and validates an API definition before implementing the API in code.
- MoesifMoesif is an API observability and product analytics platform for collecting, analyzing, and reporting API experience and usage data.
- API productAn API product is a managed and packaged API solution that exposes capabilities for consumers and includes documentation, support, and operational or commercial characteristics.
- source of truthA source of truth is the authoritative artifact or system whose state defines the intended state of related artifacts or systems.
- GitHub ActionsGitHub Actions is a GitHub service for automating software development workflows, including continuous integration and continuous delivery.
- behavioral dataA user action is an event representing an action performed by a user through a user interface.
- user funnel analysisUser funnel analysis is a method for measuring progression and drop-off across ordered user journey stages.
- api artifactAn API artifact is an API definition file or a derived product such as documentation, a client SDK, an alternative API format, or a scoring report.
- code ownershipA code owner is an individual or team designated to review and approve changes to specified files, file types, or directories in a version-controlled repository.
- value stream mappingValue stream mapping is a lean analysis technique that visualizes the flow of work and information through a process to identify waste and improvement opportunities.
- wasteWaste is process effort or elapsed time that does not contribute value to delivering the intended product or change.
- artifact repositoryAn artifact repository is a versioned repository service that stores and publishes software packages, binary artifacts, and their metadata for later consumption.
- declarative configurationDeclarative configuration specifies a system's desired state while leaving a tool or agent to determine and execute the commands needed to achieve it.
- configuration as codeConfiguration as code is the management of application configuration through descriptive, version-controlled files.
- contractAn API is a defined set of functions and protocols forming a shared boundary through which software systems communicate and exchange information.
- driftConfiguration drift is a divergence between a system's desired configuration and its actual deployed configuration.
- gemba walkGemba is the lean practice of observing work directly at the place where it is performed to understand actual conditions and causes of problems.
- work in progressWork in process inventory is partially completed work awaiting further processing or delivery.
- value streamA value stream is the complete sequence of activities and information flows required to create and deliver a product or service.
- api governanceAPI governance is the set of policies, standards, reviews, and controls that guide the design, delivery, quality, and operation of APIs.
- configuration repositoryAn environment repository is a version-controlled repository containing the desired configuration for a deployment environment.
- external mock APIA mock API, or API simulation, is a simulated API that accepts representative requests and returns representative responses without requiring the actual API implementation.
- lean principleLean thinking is a management and improvement approach that maximizes customer value while minimizing waste and pursuing continuous improvement.
- oasdiffoasdiff is an open-source command-line tool that compares OpenAPI specifications and detects differences, including potentially breaking API changes.
- process mapProcess mapping is the visual representation of a process's steps, sequence, work items, and performance characteristics.
- plan-do-check-act cycleThe plan-do-check-act (PDCA) cycle is an iterative improvement method that plans an intervention, implements it, checks the results, and acts on the findings.
- goalA goal statement is a measurable objective that defines the performance improvement and time frame used to judge success.
- custom functionA custom Spectral function is a user-defined callable extension that performs bespoke validation for a Spectral rule.
- clientClient code is software that calls an API according to its defined interface.
- api standardAn API standard is a prescribed rule or convention for designing and delivering APIs consistently and compliantly.
- API securityAPI security is the protection of information exchanged through APIs and the reduction of risks arising from API vulnerabilities.
- api diff toolAn OpenAPI diff tool compares OpenAPI definitions across versions and reports their changes, including potentially breaking changes.
- code generationCode generation is the automated production of source code or scaffolding from a formal specification or other input.
- endpointAn API endpoint is a network-accessible interface location through which a client invokes a particular API resource or operation.
- repositoryA Git-managed repository containing files, revision history, and metadata for collaborative versioned development.
- JSON path languageA JSONPath expression is a query expression that selects or navigates elements in a JSON document.
- DevOpsDevOps is a software delivery approach that integrates development and operations through lean principles, automation, feedback, and continuous learning.
- infrastructure as codeInfrastructure as code is the declarative definition and management of infrastructure resources and topologies in version-controlled files.
- observabilityObservability is the ability to query and analyze instrumented system behavior to determine the causes of previously unanticipated problems.
- countermeasureA countermeasure is an action intended to reduce or eliminate a root cause in the current situation without necessarily being a final solution.
- api registryAn API registry is a runtime system that allows users to upload and share API definition files so API consumers can browse, search, and view API details.
- breaking changeA breaking change is an API modification that can cause existing consumers or integrations to stop working.
- domain modelA domain model is a structured representation of business concepts, relationships, and workflows as interconnected software objects with behavior and data.
- API design proposalAn API design proposal is a proposed specification of an API's interface, behavior, and interaction conventions submitted for consideration before implementation.
- stateThe actual state is the configuration state that an API system currently has in operation.
- CPU timeTask time, or touch time, is the time during which work is actively performed on a process task, excluding waiting and interruptions.
- percentage complete and accuratePercentage complete and accurate (%CA) is the proportion of work items that are complete and correct without defects, missing information, or rework.
- consistencyAPI consistency is the degree to which APIs follow coherent and uniform interface, behavior, and design conventions.
- data modelA data model is a representation of the data entities, attributes, relationships, and constraints handled by a system or API.
- value-adding workValue-adding work, or a value-added activity, is process work that directly contributes to an outcome valued by the customer.
- SchemathesisSchemathesis is an open-source tool that generates and executes property-based tests for web APIs from API schemas such as OpenAPI definitions.
- pull request buildA pull request build is an automated validation build triggered for a pull request to provide feedback on changes before integration.
- pull request templateA pull request template is a predefined form or document that prompts contributors to provide standardized information with a proposed code change.
- seven wastes of leanThe seven wastes of lean are the standard categories of nonvalue-adding activity identified in lean production: defects, overproduction, work in process, unnecessary processing, unnecessary motion, unnecessary transport, and waiting.
- value-enabling workValue-enabling work does not directly create the finished customer-valued output but is required under current conditions for value-adding work to occur.
- decKdecK is a command-line tool for declaratively managing and synchronizing Kong Gateway configuration and detecting configuration drift.
- Kusk API GatewayKusk API Gateway is an open-source API gateway built on the Envoy proxy that supports embedding gateway configuration in OpenAPI definitions.
- Kusk CLIKusk CLI is a command-line tool for deploying and managing Kusk API Gateway configuration.
- error rateAn error rate is the proportion of API requests or operations that result in errors within a defined period.
- ubiquitous languageUbiquitous language is a shared vocabulary used consistently by a development team and domain stakeholders to describe a domain and its software.
- acquisition metricAn acquisition metric measures developers' initial sign-up or adoption of an API.
- activation metricAn activation metric measures the transition of an API user from evaluation to active use in an application or production environment.
- bounce rateA bounce rate is the fraction of visitors who leave a site after viewing an entry page without continuing to another page.
- customer churnChurn is the percentage of users who stop using an API during a defined period.
- discovery metricA discovery metric measures how effectively marketing channels make potential API consumers aware of an API product.
- experience metricAn experience metric measures customer satisfaction with the overall experience of an API product.
- cohortA cohort is a group of users classified by the date of their first API request.
- recurring usageRecurring usage is the API call volume generated over a recurring daily, weekly, or monthly period.
- time to valueTime to value is the elapsed time until an API user completes a business transaction representing significant value.
- user engagementAn engagement metric measures the extent to which potential API consumers interact with API documentation and developer portal tools.
- vanity metricA vanity metric is a measure that does not provide actionable understanding for improving product performance.
- business contextBusiness context is the organizational, departmental, and goal-related information that explains why a problem matters.
- api artifact storeAn API artifact store is a storage system that retains generated API artifacts and supports their retrieval by teams and applications.
- prose lintingProse linting is automated analysis of written documentation for punctuation, spelling, grammar, and language-style problems.
- reconciliationContinuous reconciliation is the repeated comparison and correction of deployed state against a declared configuration state.
- schemaA schema is a formal description of the structure, data types, properties, and constraints of data exchanged by an API.
- breaking change checkA breaking change check detects changes between API versions that can cause existing consumers or implementations to stop working.
- language modelA large language model is a machine-learning model trained on extensive text data to generate and transform natural-language or code-based content.
- domain-driven designDomain-driven design is an approach to software design that centers the structure and language of software on the underlying business domain.
- api modelAn API model is a conceptual representation of an API's business operations and data models before they are expressed in an API definition.
- API keyAn API key is a credential used to identify or authorize a client requesting access to an API.
- quality gateA security quality gate is a pipeline control that permits progression only when security evaluation results satisfy a defined threshold.
- developer experienceDeveloper experience is the overall ease, effectiveness, and satisfaction developers have when discovering, learning, using, and integrating with software products and APIs.
- software artifactA software artifact is a generated build output, such as compiled code, a release package, or an SDK, that can be stored and delivered.
- vulnerabilityA vulnerability is a weakness in software or its configuration that can be exploited to cause harm or bypass intended protections.
- developer portalA developer portal is an online platform that provides API documentation, discovery, access, and related resources to API consumers.
- manifest fileA deployment manifest is a declarative file that specifies the resources and configuration required to deploy an application or service.
- configuration state fileA configuration state file is a version-controlled file that declares the configuration state of a managed system.
- GitOps operatorA GitOps operator is software that continuously monitors a system and synchronizes it with desired configuration from a source such as a Git repository.
- pull-based deploymentA pull-based deployment is a deployment model in which an agent in or near the target environment retrieves and applies desired configuration changes.
- push-based deploymentA push-based deployment is a deployment model in which a pipeline applies configuration changes to a target environment.
- sunset strategySunsetting is the process of making an API or endpoint unavailable in production after its deprecation period ends.
- RED methodThe RED method is a monitoring approach that evaluates request rate, error rate, and request duration for a service.
- ValeVale is a configurable prose linter that checks documents against language style guides and supports formats including Markdown, AsciiDoc, and reStructuredText.
- API versionAn API version identifier is a value that distinguishes a particular version of an API, resource, or endpoint contract.
- CODEOWNERS fileA CODEOWNERS file is a repository configuration file that maps specified files, file types, or directories to the individuals or teams responsible for reviewing changes.
- customer journeyA user journey is the sequence of stages and actions an actor performs while interacting with a product or service to achieve a goal.
- fuzzingFuzz testing is a technique that tests software by generating and submitting random, malformed, or semi-malformed inputs to expose defects.
- product analyticsProduct analytics is the analysis of user interactions and product behavior to understand and improve a product's value and experience.
- additionalPropertiesadditionalProperties is an OpenAPI schema keyword that specifies whether object properties not declared in the schema are allowed.
- Atlassian Swagger Request Validatorswagger-request-validator-mockmvc is an Atlassian library module that validates HTTP requests and responses against OpenAPI descriptions and integrates with MockMvc.
- GitHub CopilotGitHub Copilot is an AI-powered software development tool that generates code and suggestions from programming context and natural-language prompts.
- api value proposition canvasAn API value proposition canvas is a structured analysis tool for relating an API consumer's pains and expected gains to an API product's value proposition.
- digital capabilityA digital capability is a high-level task or functional ability that a digital product or API must provide to support a business job.
- job storyA job story is a requirements statement describing a triggering situation, a user's motivation or goal, and an expected outcome.
- job to be doneJobs to Be Done is a framework for identifying the goals and underlying needs that motivate customers to use or purchase a product or service.
- pull request description policyA pull request description policy specifies required content or validation rules for descriptions accompanying proposed code changes.
- performanceA performance metric is a quantitative measure of process or system performance used for comparison and evaluation.
- Spring BootSpring Boot is a Java framework for building stand-alone, production-oriented applications with convention-based configuration and embedded infrastructure.
- validation annotationA validation annotation is a declarative annotation that specifies constraints to be checked on input or model data.
- stability levelA stability version is a named API version designation that communicates the maturity and expected stability of the API.
- end-to-end testingAn end-to-end test verifies behavior across an entire application or service interaction path, including its external interfaces and dependent components.
- property-based testingProperty-based testing is a technique that generates many test cases from specified data properties or input strategies.
- AI agentA software agent is an automated software component that observes system state and performs actions to create, configure, or manage deployed applications.
- cause analysisRoot-cause analysis is a systematic examination of underlying causes that explains the relationship between an observed effect and its cause.
- api patternAn API design pattern is a reusable solution structure for designing API interfaces and interactions.
- target conditionA target condition is the defined future state of a process after proposed improvements have been implemented.
- continuous deploymentContinuous deployment is the practice of automatically deploying every change that passes all delivery-pipeline stages to production without human intervention.
- non-production testingNon-production testing is the evaluation of software in environments other than production using user-oriented acceptance, performance, security, and related tests.
- release candidateA release candidate is a packaged software version considered sufficiently complete for deployment to further testing or production environments.
- compliance checkAn API compliance check is an automated or manual verification that an API definition conforms to applicable governance standards.
- mean time to resolutionMean time to restore is the average time required to recover a failed service or system to working condition.
- OpenAPI extensionAn OpenAPI extension is a specification-defined mechanism for adding custom fields beginning with x- to an OpenAPI document.
- testA unit test is an automated test that evaluates a small, isolated software unit independently of its external dependencies.
- threat modelThreat modeling is the systematic identification and analysis of threats, vulnerabilities, likelihood, impact, controls, and countermeasures affecting a software system.
- API Security Top 10The OWASP API Security Top 10 is an industry awareness document describing and ranking prevalent security risks specific to APIs.
- pull requestA pull request is a proposed change submitted for review and integration into a version-controlled codebase.
- throughputThroughput is the amount of work or number of requests processed by a system within a specified time interval.
- api version migrationAPI version migration is the process of moving API consumers or providers from one API version to another.
- compatible migration patternThe Compatible migration pattern is an API migration strategy in which one API service handles requests from consumers using multiple compatible API versions.
- knot migration patternThe Knot migration pattern is an API migration strategy in which all consumers and the surrounding ecosystem migrate together to a new API version.
- point-to-point migration patternThe Point-to-Point migration pattern is an API migration strategy in which different API versions remain deployed so consumers can migrate independently.
- version change moduleA version change module is a separate code component that transforms an API resource or response between API versions.
- Redocly CLIRedocly is a toolset for rendering, documenting, validating, and managing APIs described with OpenAPI.
- deprecationThe deprecated stability level denotes an API version that is scheduled for removal.
- sad pathA sad path is an API execution path in which an error or exceptional condition produces an unsuccessful response.
- given propertyA given property is a Spectral rule property containing JSONPath expressions that select the document elements to which the rule applies.
- then propertyA then property is a Spectral rule property that specifies the function and optional field used to evaluate selected input.
- Spectral truthy functionThe truthy function reports a violation when its input is false, empty, zero, null, or undefined.
- JSON PointerJSON Pointer is a string syntax for identifying a specific value within a JSON document.
- big bang consistency approachA big bang consistency approach brings an existing API and its implementation into compliance with a ruleset through a single broad update.
- gradual consistency approachA gradual consistency approach applies a shared ruleset incrementally by selectively enabling, disabling, or regrading rules for specific API objects.
- multi-ruleset consistency approachA multi-ruleset consistency approach assigns a separate, typically reduced ruleset to each API project.
- overrideA Spectral override is a configuration that changes rule applicability or severity for selected API documents or objects.
- GitHub actionA GitHub Actions action is a custom application that performs a reusable task within a GitHub Actions workflow.
- code-first approachAn API development practice that implements an API in code from business requirements and generates its API definition afterward.
- security threatA threat is a potential occurrence that can damage or compromise a business asset or objective.
- service-level indicatorA service level indicator is a quantitative measure of an aspect of a service's health or performance.
- url pathA URI path is the path component of a uniform resource identifier that identifies a resource or resource hierarchy in an API.
- api product managerAn API product manager is the role responsible for defining, guiding, and managing API products.
- bundlingBundling is the technique of combining an API document with the definitions referenced from other files or URLs into a single document.
- backward compatibilityAPI compatibility is the ability of an API client application and API server to communicate successfully across a change.
- commit policyA commit policy is a set of automated rules evaluated against new commits to accept or reject them according to project requirements.
- git hookA Git hook is a customizable script that runs automatically in response to an event in a Git repository.
- PrismPrism is an open-source proxy and mock server for validating and simulating APIs described by OpenAPI definitions or Postman collections.
- PortmanPortman is a command-line tool that generates and executes Postman collections for testing API implementations against OpenAPI definitions.
- child documentAn external API fragment is a separately stored JSON or YAML document containing part of an API definition that is referenced from a parent document.
- idempotencyIdempotency is the property of an operation whose repeated execution produces the same resulting server state as a single execution.
- idempotency keyAn idempotency key is a client-supplied identifier that lets an API detect and handle duplicate requests for an operation.
- API review checklistAn API review checklist is an ordered set of inspection criteria for evaluating an API design.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.