RAPID-ML™, the Modeling Language for Resource API over Data, is a structured language for comprehensively describing and documenting data-oriented, REST-style APIs. RAPID-ML can be used by generators or runtime interpreters for API documentation, visualization, data schemas, test frameworks, client SDKs and service implementations.
RAPID-ML is designed for general-purpose API modeling, emphasizing a few areas of particular importance:
|•||RAPID-ML enables the definition and documentation of shared, canonical data models using RAPID-Schema™, a domain-driven, technology-neutral data modeling language. RAPID-Schema models capture the data semantics that are meaningful in APIs, without syntactic noise or unnecessary complexity associated with specific message formats. RAPID-ML and RAPID-Schema leave most of the wire format details to be handled by message schema generators.|
|•||RAPID-ML adapts these shared models to meet the needs of a particular API usage context. RAPID-ML uses the term realization to describe a data type adapted for use in a given resource or message. Realizations vary from their underlying data types only in well-defined ways that do not break conformance with the underlying data model. This constrained variation promotes interoperability by making it practical for APIs to converse in a common, structured data vocabulary.|
|•||RAPID-ML supports formal binding of data models into the API. Resources may be bound to data structures. URI and message parameters may be bound to data properties. Hyperlinking and embedding may be defined by reference properties in the underlying data structures. These data binding semantics capture common REST idioms in a concise, natural way, and enable more complete downstream implementation of the API's intended behavior.|
|•||RAPID-ML uses a highly readable, indent-based syntax that features optional fluency. The language syntax includes optional fluency keywords that have no semantic effect, but serve to make the syntax more natural. By including or omitting these optional keywords, developers can adopt a fluent or terse coding style.|
This specification provides all the information necessary to describe resource APIs RAPID-ML and their associated data types RAPID-Schema.