apiaryio/api-blueprintArchived
Api Blueprint
api-blueprint is a markdown-based API design language and specification standard used to define the structure, behavior, and data schemas of HTTP web services. It provides a formal method for mapping HTTP methods to resources and defining payload validation rules through a machine-readable syntax.
The project functions as a blueprint for creating interactive technical documentation and functional mock servers. These tools transform design specifications into human-readable guides and simulated backend environments to enable integration testing before implementation.
The language covers API modeling through the definition of request and response schemas, resource organization using URI templates, and the specification of client-server interaction cycles. It utilizes an abstract syntax tree to parse specifications, supporting schema-driven payload validation and template-based documentation generation.
Features
- RESTful API Designs - Provides a markdown-based language for designing the structure and behavior of RESTful web services.
- Web API Design Patterns - Defines the structure and behavior of web services using a concise syntax for prototyping and documenting interfaces.
- API Documentation Generators - Provides tools to automatically transform API design specifications into interactive technical documentation guides.
- API Design Languages - Ships a markdown-based specification language for defining HTTP web service structures and schemas.
- Specification Languages - Uses a human-readable markdown-based text format to describe API resources and data structures.
- API Resource Modeling - Organizes web endpoints into groups and resources by defining URI templates and available actions.
- API Specification Definitions - Details the interaction between client and server by defining request parameters, headers, and responses.
- Data Schema Definitions - Defines the structure of request and response payloads using named types to ensure consistent data exchange.
- Data Validation Schemas - Defines expected data shapes to automatically verify that request and response bodies adhere to specific types.
- HTTP Interface Definitions - Implements a formal method to map HTTP methods to resources and define payload validation rules.
- Schema-Driven Mocking - Automatically generates a functional server that simulates API responses based on defined request and response cycles.
- API Mocking Servers - Generates functional mock servers from design specifications to enable integration testing before backend implementation.
- Request Body Validations - Creates schemas to validate the structure and content of request and response message bodies.
- REST API Specifications - Provides a standard for describing resources, request parameters, and response payloads for consistency.
- API Reference Generators - Transforms machine-readable API definitions into formatted interactive guides and technical reference manuals.
- Message Body Notations - Provides a markdown-based notation for defining the organization and attributes of message-body data.
- API Data Shapes - Allows the description of complex data shapes using human-readable text to create reusable API components.
- Schema Definitions - Specifies the allowed structure, member types, and required fields for JSON response bodies.
- Specification Parsers - Converts design language into machine-readable interfaces via an abstract syntax tree to support custom tooling.
- Specification AST Generation - Converts design documents into structured abstract syntax trees for programmatic analysis and tool generation.
- URI Parameter Definitions - Defines the expected data types and descriptions for variables used within a URI template.
- API Interface Prototyping - Enables rapid modeling of HTTP endpoints and data structures to validate interfaces before implementation.
- URI Template Mappings - Maps HTTP methods and path variables to specific service resources to define the web service interaction model.
- Mocking Specifications - Provides a blueprint for creating functional mock servers that simulate backend behavior for testing.
- Service Method Mapping - Maps HTTP methods to specific resources to define the request and response cycle of a web service.
- API Specification Tools - A markdown-based language for describing web APIs.
- Documentation Frameworks - High-level language for describing web APIs.
- Documentation Generators - High-level language for describing web APIs.
