telemetrik / api-blueprint

API Blueprint

API Blueprint

API Design for Humans

API Blueprint is a documentation-oriented API description language. A couple of semantic assumptions over the plain Markdown.

API Blueprint is perfect for designing your Web API and its comprehensive documentation but also for quick prototyping and collaboration. It is easy to learn and even easier to read – after all it is just a form of plain text.

API Blueprint, its parser, and most of its tools are completely open sourced so you don't have to worry about vendor lock-in. This also means you can freely integrate API Blueprint into any type of product, commercial or not.

TL;DR

• Web API description language
• Pure Markdown
• Designed for humans
• Understandable by machines
• Open & free

Format support

• Current format: 1A9
• Format supported by Apiary: 1A8

Getting started with API Blueprint

All it takes to describe that message endpoint of your API is to write:

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

        Hello World!

in your favourite Markdown editor. With this API description in your API GitHub repository you can discuss it with others and iterate on your API Design.

To learn more about the API Blueprint syntax jump directly to the API Blueprint Tutorial or take a look at some examples.

Complete Lifecycle

Describing your API is only the start. The API Blueprint can be used by variety of tools from an interactive documentation, SDK generator, debugging proxy and mock server to API testing and analytics tools.

Visit the tooling section of the API Blueprint website to find more about the tools you can use with API Blueprint.

Machines

Building tools for API Blueprint is possible thanks to its machine-friendly face:

{
    "_version": "2.0",
    "metadata": [],
    "name": "",
    "description": "",

    ...
}

[full listing]

It is the task for the API Blueprint parser – Drafter or one of its language bindings to translate the API Blueprint Markdown representation into a machine friendly format – AST.

If you are interested in building tools for API Blueprint or just to integrate it with your workflow check out the Developing tools for API Blueprint.

Media Type

The media type for API Blueprint is text/vnd.apiblueprint+markdown.

Learn more

• Tutorial
• Examples
• Glossary of Terms
• API Blueprint Map
• Language Specification
• Tools working with API Blueprint

Developers

• API Blueprint reference parser – Drafter
• Drafter Bindings to other languages
• API Blueprint AST Serialization Media Types
• Developing tools for API Blueprint

Future of API Blueprint

Check out the API Blueprint Issues Page for planned features and issues discussion along with our RFC process for accepted language changes.

Contribute

We use an RFC process for proposing any substancial changes to the API Blueprint language, specification and/or parsers.

If you would like to propose a change, please consult our RFC process.

Have a question?

Ask at Stack Overflow, make sure to use the apiblueprint tag. Alternatively mention @apiblueprint on Twitter.

License

MIT License. See the LICENSE file.