As of 2015-12-02 the API Blueprint AST is deprecated and should not be used for new development. The API Blueprint AST has been superseded by API Elements.
API Blueprint AST is JSON or YAML, machine-friendly, face of API Blueprint suitable for use in tools consuming (or producing) API Blueprint.
This document defines serialization formats for API Blueprint abstract syntax tree, or AST for short.
For the definition of API Blueprint AST Source Map see the API Blueprint AST Source Map definition.
Converting API Blueprint to AST and its serialization is the task of API Blueprint Parser – Drafter or one of its bindings. Reverse process from AST (serialization) to API Blueprint is also possible thanks to the Matter Compiler.
If you are looking for a way to describe your Web API without using JSON or YAML see API Blueprint.
- Version: 4.0
- Created: 2013-08-30
- Updated: 2015-09-07
As of version 3.0 the API Blueprint AST is in the interim transition period towards unified document-structure based on the concept of DOM elements (see the Element object). Please refrain from using AST elements marked as "deprecated".
- AST Description
- Media Types
- Keys description
- Example: JSON serialization
- Serialization in Drafter
- Serialized Parsing Result Media Types
Following is the definition of API Blueprint AST media types using the MSON syntax.
NOTE: Most of the keys corresponds to their counter parts in API Blueprint Specification. Where applicable, refer to the relevant entry API Blueprint Language Specification for details.
-
_version(string) - Version of the AST Serialization as defined in this document -
metadata(array) - Ordered array of API Blueprint metadata- (object)
name(string) - Name of the metadatavalue(string) - Value of the metadata
- (object)
-
name(string) - Name of the API -
description(string) - Top-level description of the API in Markdown (.raw) or HTML (.html) -
resourceGroups(array[Resource Group]) - DeprecatedNote this property is deprecated and will be removed in a future. Replaced by
categoryelements of thecontentproperty. -
element:category(fixed, required) -
content(array[Element]) - Section elements of the blueprint
A component of an API description.
element(enum[string]) - Element namecategory- Element is a group of other elementscopy- Element is a human readable textresource- Element is a ResourcedataStructure- Element is a Data Structure definitionasset- Element is an asset of API description
attributes(object) - Element-specific attributesname(string, optional) - Human readable name of the element
content(enum)- (array[Element]) - Ordered array of nested elements (for element
category) - (string) - Markdown-formatted text (for element
copyandassettype) - (Resource) - Resource definiton (for element
resource) - (Data Structure) - Data structure (for element
dataStructure)
- (array[Element]) - Ordered array of nested elements (for element
Deprecated, replaced by the category Element.
Logical group of resources.
name(string) - Name of the Resource Groupdescription(string) - Description of the Resource Group (.rawor.html)resources(array[Resource]) - Ordered array of the respective resources belonging to the Resource Group
Description of one resource, or a cluster of resources defined by its URI template.
-
name(string) - Name of the Resource -
description(string) - Description of the Resource (.rawor.html) -
element:resource(fixed, required) -
uriTemplate(string) - URI Template as defined in RFC6570 -
model(Payload) - Resource Model, a reusable payload representing the resource -
parameters(array[Parameter]) - Ordered array of URI parameters -
actions(array[Action]) - Ordered array of actions available on the resource each defining at least one complete HTTP transaction -
content(array[Data Structure]) - Array of Resource's elementsIn the interim period this may contain at maximum one element of the
dataStructuretype - the definition of the of the Resource attributes.
An HTTP transaction (a request-response transaction). Actions are specified by an HTTP request method within a resource.
-
name(string) - Name of the Action -
description(string) - Description of the Action (.rawor.html) -
method(string) - HTTP request method defining the action -
parameters(array[Parameter]) - Ordered array of resource's URI parameters descriptions specific to this action -
examples(array[Transaction Example]) - Ordered array of HTTP transaction examples for the relevant HTTP request method -
attributes(object) - Action-specific attributesuriTemplate(string) - URI Template as defined in RFC6570relation(string) - Link relation identifier of the action as defined in Relation section
-
content(array[Data Structure]) - Array of Action's elementsIn the interim period this may contain at maximum one element of the
dataStructuretype - the definition of the of the action input attributes.
-
name(string) - Name of the payloadThe content of this key depends on the type of payload:
- model payload: name of the resource, if any
- request payload: name of the request, if any
- response payload: HTTP status code
-
reference(Reference) - Present if and only if a reference to a Resource Model is present in the payload and it has been resolved correctly -
description(string) - Description of the payload (.rawor.html) -
headers(array[[Header][]]) - Ordered array of HTTP headers that are expected to be transferred with HTTP message represented by this payload -
body(string) - DeprecatedAn entity body to be transferred with HTTP message represented by this payload
Note this property is deprecated and will be removed in a future. Replaced by
bodyExampleAsset element. -
schema(string) - DeprecatedA validation schema for the entity body as defined in
body.Note this property is deprecated and will be removed in a future. Replaced by
bodySchemaassetelement. -
content(array) - Array of Payloads's elementsIn the interim period this may contain only:
-
At maximum one element of the
dataStructuretype - the definition of the message-body attributes -
Up to two asset elements one for body example other for body schema
-
Items
- (Data Structure)
- (Asset)
-
A HTTP header that are expected to be transferred with an HTTP message.
name(string, required) - The name of the headervalue(string, required) - The value of the header
An API Blueprint asset. The content is an Asset in its textual representation as written in the source API Blueprint.
element:asset(fixed, required)attributesrole- Role of the assetbodyExample- Asset is an example of message-bodybodySchema- Asset is an schema for message-body
Description of one URI template parameter.
name(string) - Name of the parameterdescription(string) - Description of the parameter (.rawor.html)type(string) - An arbitrary type of the parameter (a string)required(boolean) - Boolean flag denoting whether the parameter is required (true) or not (false)default(string) - A default value of the parameter (a value assumed when the parameter is not specified)example(string) - An example value of the parametervalues(array) - An array enumerating possible parameter values- (object)
value(string) - Value choice of for the parameter
- (object)
An HTTP transaction example with expected HTTP message request and response payload(s).
name(string) - Name of the Transaction Exampledescription(string) - Description of the Transaction Example (.rawor.html)requests(array[Payload]) - Ordered array of example transaction request payloadsresponses(array[Payload]) - Ordered array of example transaction response payloads
A reference object which is used whenever there is a reference to a Resource Model.
id(string) - The identifier (name) of the reference
The application/vnd.apiblueprint.ast is the media type for API Blueprint AST. The media type serialization format is specified in the +<serialization format> appendix.
Two supported, feature-equal serialization formats are JSON and YAML:
application/vnd.apiblueprint.ast.jsonapplication/vnd.apiblueprint.ast.yaml
application/vnd.apiblueprint.ast.json; version=4.0
{
"_version": "<AST version>",
"metadata": [
{
"name": "<metadata key name>",
"value": "<metadata value>"
}
],
"name": "<API name>",
"description": "<API description>",
"element": "category",
"content": [
{
"element": "category",
"attributes": {
"name": "<resource group name>"
},
"content": [
{
"element": "copy",
"content": "<resource group description>"
},
{
"name": "<resource name>",
"description": "<resource description>",
"element": "resource",
"uriTemplate": "<resource URI template>",
"model": {
"name": "<resource model name>",
"description": "<resource model description>",
"headers": [
{
"name": "<HTTP header field name>",
"value": "<HTTP header field value>"
}
],
"content": [
{
"element": "dataStructure",
"content":{
"element": "object",
"meta": {
"ref": "<sub-type>"
},
"content": []
}
},
{
"element": "asset",
"attributes": {
"role": "bodyExample"
},
"content": "<resource model body>"
},
{
"element": "asset",
"attributes": {
"role": "bodySchema"
},
"content": "<resource model schema>"
}
]
},
"parameters": [
{
"name": "<name>",
"description": "<description>",
"type": "<type>",
"required": "<required parameter flag>",
"default": "<default value>",
"example": "<example value>",
"values": [
{
"value": "<enum element>"
}
]
}
],
"actions": [
{
"name": "<action name>",
"description": "<action description>",
"method": "<action HTTP request method>",
"parameters": [
{
"name": "<name>",
"description": "<description>",
"type": "<type>",
"required": "<required parameter flag>",
"default": "<default value>",
"example": "<example value>",
"values": [
{
"value": "<enum element>"
}
]
}
],
"examples": [
{
"name": "<transaction example name>",
"description": "<transaction example description>",
"requests": [
{
"name": "<request name>",
"description": "<request description>",
"headers": [
{
"name": "<HTTP header field name>",
"value": "<HTTP header field value>"
}
],
"content": [
{
"element": "dataStructure",
"content": {
"element": "object",
"meta": {
"ref": "<sub-type>"
},
"content": []
}
},
{
"element": "asset",
"attributes": {
"role": "bodyExample"
},
"content": "<request body>"
},
{
"element": "asset",
"attributes": {
"role": "bodySchema"
},
"content": "<request schema>"
}
]
}
],
"responses": [
{
"name": "<response HTTP status code>",
"description": "<response description>",
"headers": [
{
"name": "<HTTP header field name>",
"value": "<HTTP header field value>"
}
],
"content": [
{
"element": "dataStructure",
"content": {
"element": "object",
"meta": {
"ref": "<sub-type>"
},
"content": []
}
},
{
"element": "asset",
"attributes": {
"role": "bodyExample"
},
"content": "<request body>"
},
{
"element": "asset",
"attributes": {
"role": "bodySchema"
},
"content": "<request schema>"
}
]
}
]
}
],
"content": [
{
"element": "dataStructure",
"content": {
"element": "object",
"meta": {
"ref": "<sub-type>"
},
"content": []
}
}
]
},
{
"name": "<action name>",
"description": "<action description>",
"method": "<action HTTP request method>",
"parameters": [],
"examples": [
{
"name": "<transaction example name>",
"description": "<transaction example description>",
"responses": [
{
"name": "<response HTTP status code>",
"reference": {
"id": "<resource model name>"
},
"description": "<resource model description>",
"headers": [
{
"name": "<HTTP header field name>",
"value": "<HTTP header field value>"
}
],
"content": [
{
"element": "asset",
"attributes": {
"role": "bodyExample"
},
"content": "<resource model body>"
},
{
"element": "asset",
"attributes": {
"role": "bodySchema"
},
"content": "<resource model schema>"
}
]
}
]
}
]
}
],
"content": [
{
"element": "dataStructure",
"content": {
"element": "object",
"meta": {
"id": "<resource-name>",
"ref": "<sub-type>"
},
"content": []
}
}
]
}
]
},
{
"element": "category",
"content": [
{
"element": "dataStructure",
"content": {
"element": "object",
"meta": {
"id": "<data-structure-name>",
"ref": "<sub-type>"
},
"content": []
}
}
]
}
]
}- Serialized Parsing Result Media Types - Media types for the serialization of complete parsing results (including warnings and errors)
The drafter command-line tool supports serialization of API Blueprint AST via the --format option. Similarly, it also supports serialization of API Blueprint Source Map using the --format and --sourcemap option.
MIT License. See the LICENSE file.