API Definition Building Blocks
As I monitor the API space I am always on the hunt for the common building blocks that make up any area of my work--these are some of the common elements I have aggregated from across the world of API definitions.
- 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.
- 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.
- 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.
- Database - Tooling that generates an API definition format from a database connection, allowing for API integration with common database formats
- Files - Mount file stores and generate API definitions and schemas from the file store structure.
- Attribution - Where did the API definition originate? Is there a source where all or part of the API design came from? Providing design, or operational attribution, done via one of the API definitions.
- Annotation - Allowing for the annotation of API definitions, schemas, as part of the API life cycle.
- Proxy - Allowing for the proxying of API requests and responses using tools like Charles Proxy, or Prism from Stoplight, and generating of API definitions and schemas from the traffic.
I am always adding to, and shifting my lists of the common building blocks as I evolve my understand of the space, and who is doing interesting things with API definitions.