API Journey

Definitions - From the simplest definition of what a service does, all the way to the complete OpenAPI definition for each service. These are the artifacts that will guide each service through every step of the API lifecycle. API definitions are not just for documentation, or for generating code, they define the contract that a service delivers.

  • Formats - Information regarding the different formats of definitions that are used across the entire API lifecycle, being applied across all of the stops along the journey.
    • Web Concepts - APIs are built on the web, and there are numerous web concepts in play that should be considered as part of the API design process.
    • Media Types - A media type (also MIME type and content type) is a two-part identifier for file formats and format contents transmitted on the Internet. The Internet Assigned Numbers Authority (IANA) is the official authority for the standardization and publication of these classifications.
    • Specification - The root specification for the API definition format, providing a base set of rules for all services and tools that employ the spec.
    • Schema - A representation of data model, used as part of an API request, or response, usually in JSON, but increasingly YAML, and Markdown are also used.
    • Container File - Leveraging and approaching management of the container configuration files used as part of the container deliver process.
    • Orchestration Artifacts - Being organized regarding how Jenkins, and other CI/CD configuration files are stored, configured, audited, and used across the lifecycle. Organized centrally, audited, and tracked upon across deployments and builds looking for patterns and eliminating unhealthy practices.
  • Tooling - Defining the tooling that are available to work with definitions, providing a wide range of benefits to working with definitions across many areas in which the definitions are used.
    • Generator - Generating an API definition format from an existing system or platform, outputting the portable machine readable format.
    • Parser - Parses a machine readable API definition and makes ready for use in specific language, structure, or platform.
    • Validator - Validates an API definition against its formal specification and schema, producing a valid or invalid response, with as much detail as possible.
    • Converter - The conversion of an API definition from one format into another, allowing designers to share API definitions in any format.
    • Command-Line - The usage of machine readable API definitions at the command line.
    • Aggregator - Aggregation of APIs using a machine readable API definition format, allowing multiple APIs to be aggregated into a single definition, either combining or merging using API definitions.
    • Merger - Tooling or other APIs that provide for the merging of common API definition formats, allowing the granularity of what elements get merged, or do not get merged. Ideally, this is an API, as well as simple web-based or desktop tooling for API providers and consumers.
    • Difference - Providing side by side comparison of two API definitions, programmatically and visually helping identify between two API definitions. This allows for API architects, designers, and consumers to understand the completeness of two definitions, in relation to each other.
  • Environment - Providing standardized environments for working with all of the definitions being used throughout the service delivery life cycle.
    • Editors - API definition editor, allowing for the creation, import, and export of API definition formats, providing a simple, IDE like API editing experience.
    • IDE Plugin - Providing integration with existing integrated development environments (IDE), giving developers API discovery, documentation, and integration tooling within the IDE.
    • Forms - Dynamically generating an HTML form from an API definition, allow for the structure, and handling to be driven by an API definition.
    • Repository - Management of all definitions within a version control system, using the underlying repository as a location to aggregate, store, and include API definitions into build pipelines.