FORMAT: 1A
HOST: https://api.apiblueprint.org

# API Blueprint API
API Blueprint API provides the access to core API Blueprint tools "as a service".

## Authentication and Rate Limiting
The access to the service does not require authentication; however it is rate-limited.

## Media Types

### Blueprint

```
text/vnd.apiblueprint+markdown
```

API Blueprint as defined in its [specification](https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md).

### Blueprint AST

```
application/vnd.apiblueprint.ast.raw+json
application/vnd.apiblueprint.ast.raw+yaml
```

Serialized API Blueprint AST is represented either in its JSON or YAML format as defined in [API Blueprint AST Serialization Media Types](https://github.com/apiaryio/api-blueprint-ast).

### Parse Result

```
application/vnd.apiblueprint.parseresult.raw+json
application/vnd.apiblueprint.parseresult.raw+yaml
```

Result of API Blueprint parsing operation. This media types includes Blueprint AST media types and additional information – parser source code annotations (warnings and errors). Defined in [Parse Result Media Types](https://github.com/apiaryio/api-blueprint-ast/blob/master/Parse%20Result.md).

### Resource State Representation

```
application/hal+json
```

Where applicable this API uses the [HAL+JSON](https://github.com/mikekelly/hal_specification/blob/master/hal_specification.md) media-type to represent resources states and provide available affordances.

## Error States
The common [HTTP Response Status Codes](https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md) are used.

# Group API

## Service Root [/]
API Blueprint API entry point.

This resource does not have any attributes, instead it provides list of available affordances.

### Affordances
- `parse` - Parse an API Blueprint into AST

    See _Blueprint Parser_ resource's _Parser_ action for details.

- `compose` - Composes an API Blueprint from an AST

    See _Blueprint Composer_ resource's _Compose_ action for details.

### List [GET]
+ Response 200 (application/hal+json)
    + Headers

            Link: <http://docs.apiblueprintapi.apiary.io>; rel="profile"

    + Body

            {
                "_links": {
                    "self": { "href": "/" },
                    "parse": { "href": "/parser" },
                    "compose": { "href": "/composer" },
                }
            }

# Group Blueprint Manipulation

## Blueprint Parser [/parser]
API Blueprint parsing as provided by the [Snow Crash](https://github.com/apiaryio/snowcrash) reference parser.

### Parse [POST]
Parse a blueprint (`text/vnd.apiblueprint+markdown`) into a serialized API Blueprint AST (`application/vnd.apiblueprint.ast.raw+json` or `application/vnd.apiblueprint.ast.raw+yaml`). The serialized Blueprint AST is returned alongside with any parser parser annotations in the form of a Parser Result (`application/vnd.apiblueprint.parseresult.raw+json` or `application/vnd.apiblueprint.parseresult.raw+yaml`).

+ Request JSON Parser Result (text/vnd.apiblueprint+markdown; version=1A; charset=utf-8)

    + Headers

            Accept: application/vnd.apiblueprint.parseresult.raw+json

    + Body

            # GET /message
            + Response 200 (text/plain)

                    Hello World!

+ Response 200 (application/vnd.apiblueprint.parseresult.raw+json; version=1.0)

        {
            "_version": "1.0",
            "ast": {
                "_version": "2.0",
                "metadata": [],
                "name": "",
                "description": "",
                "resourceGroups": [
                    {
                        "name": "",
                        "description": "",
                        "resources": [
                            {
                                "name": "",
                                "description": "",
                                "uriTemplate": "/message",
                                "model": {},
                                "parameters": [],
                                "actions": [
                                    {
                                        "name": "",
                                        "description": "",
                                        "method": "GET",
                                        "parameters": [],
                                        "examples": [
                                            {
                                                "name": "",
                                                "description": "",
                                                "requests": [],
                                                "responses": [
                                                    {
                                                        "name": "200",
                                                        "description": "",
                                                        "headers": [
                                                            {
                                                                "name": "Content-Type",
                                                                "value": "text/plain"
                                                            }
                                                        ],
                                                        "body": "Hello World!\n",
                                                        "schema": ""
                                                    }
                                                ]
                                            }
                                        ]
                                    }
                                ]
                            }
                        ]
                    }
                ]
            },
            "error": null,
            "warnings": []
        }

+ Request YAML Parser Result (text/vnd.apiblueprint+markdown; version=1A; charset=utf-8)

    + Headers

            Accept: application/vnd.apiblueprint.parseresult.raw+yaml

    + Body

            # GET /message
            + Response 200 (text/plain)

                    Hello World!

+ Response 200 (application/vnd.apiblueprint.parseresult.raw+yaml; version=1.0)

        _version: 1.0
        ast:
            _version: 2.0
            metadata:
            name:
            description:
            resourceGroups:
            -   name:
                description:
                resources:
                -   name:
                    description:
                    uriTemplate: "/message"
                    model:
                    parameters:
                    actions:
                    -   name:
                        description:
                        method: "GET"
                        parameters:
                        examples:
                        - name:
                            description:
                            requests:
                            responses:
                            -   name: "200"
                                description:
                                headers:
                                -   name: "Content-Type"
                                    value: "text/plain"
                                body: "Hello World!\n"
                                schema:
        error: null
        warnings: []


## Blueprint Composer [/composer]
API Blueprint AST Media Types to API Blueprint conversions as provided by the [Matter Compiler](https://github.com/apiaryio/matter_compiler) tool.

### Compose [POST]
Convert a serialized API Blueprint AST (`application/vnd.apiblueprint.ast.raw+json` or `application/vnd.apiblueprint.ast.raw+yaml`) into API Blueprint (`text/vnd.apiblueprint+markdown`).

+ Request (application/vnd.apiblueprint.ast.raw+yaml; version=2.0)

        _version: 2.0
        metadata:
        name:
        description:
        resourceGroups:
        -   name:
            description:
            resources:
            -   name:
                description:
                uriTemplate: "/message"
                model:
                parameters:
                actions:
                -   name:
                    description:
                    method: "GET"
                    parameters:
                    examples:
                    - name:
                        description:
                        requests:
                        responses:
                        -   name: "200"
                            description:
                            headers:
                            -   name: "Content-Type"
                                value: "text/plain"
                            body: "Hello World!\n"
                            schema:

+ Request (application/vnd.apiblueprint.ast.raw+json; version=2.0)

        {
            "_version": "2.0",
            "metadata": [],
            "name": "",
            "description": "",
            "resourceGroups": [
                {
                    "name": "",
                    "description": "",
                    "resources": [
                        {
                            "name": "",
                            "description": "",
                            "uriTemplate": "/message",
                            "model": {},
                            "parameters": [],
                            "actions": [
                                {
                                    "name": "",
                                    "description": "",
                                    "method": "GET",
                                    "parameters": [],
                                    "examples": [
                                        {
                                            "name": "",
                                            "description": "",
                                            "requests": [],
                                            "responses": [
                                                {
                                                    "name": "200",
                                                    "description": "",
                                                    "headers": [
                                                        {
                                                            "name": "Content-Type",
                                                            "value": "text/plain"
                                                        }
                                                    ],
                                                    "body": "Hello World!\n",
                                                    "schema": ""
                                                }
                                            ]
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                }
            ]
        }

+ Response 200 (text/vnd.apiblueprint+markdown; version=1A)

        # /message
        ## GET
        + Response 200 (text/plain)

                Hello World!