API Definitions Building Blocks

As I study the API space, and profile the companies, services, and tooling I come across I'm always looking for the common building blocks in use across API operations. These are the features, and valuable elements of API operations, as well as companies who are servicing the API space.

  • Formats
    • 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.
    • 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.
  • Tooling
    • 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.
    • Powershell - The usage of machine readable API definitions via the powershell interface.
    • Aggregator - Aggregation of APIs using a machine readable API definition format.
    • Translator - Being able to translate an API definition format from one format to another, either manually or automatically.
    • Merging - 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.
    • Diff - 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
    • 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.
    • GIthub - Allowing for the import, publishing, and syncing of API definitions and schemas to Github for forking, and management using the social coding platform.

These building blocks are constantly being added to and reorganized. If there is something you think should be here feel free to let me know. Remember that this represents my living research, and will evolve, expand and actually seed new research areas as I find the time to pay attention to API definitions.