seemsindie / 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

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 – Snow Crash 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.

Learn more

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

Developers

• API Blueprint reference parser – Snow Crash
• Snow Crash 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.

Contribute

Fork & pull request.

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.