API Blueprint

API design for humans

API Blueprint is a documentation-oriented API description language. A couple of semantical 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 Markdown.

TL;DR

Web API description language
Pure Markdown
Designed for humans
Understandable by machines

Getting started with API Blueprint

All it really takes to describe an endpoint of your API is write something like this:

# GET /message
+ Response 200 (text/plain)
    
        Hello World!

in your favorite Markdown editor. Now you can share and discuss this API in your API repository and let GitHub to render the API documentation so others can see it.

Jump directly to the API Blueprint Tutorial or browse the interactive examples to learn more about the API Blueprint syntax.

Describing your API is only the start. The API Blueprint can be used by variety of tools from interactive documentation and code generators to API testing tools thanks to its machine-friendly face:

{
  "_version": "1.0",
  "metadata": {},
  "name": "",
  "description": "",
  "resourceGroups": [
    {
        ...

[full listing]

It it the task of the native API Blueprint parser or one of its bindings to "translate" the API Blueprint Markdown representation into a machine friendly format – AST.

Visit the tooling section of the API Blueprint website to find more about the actual tools or check the Developing tools for API Blueprint if you are interested in using API Blueprint in your tool chain.

Learn more

Developers

Future of API Blueprint

Discuss and influence the future of API Blueprint in its Milestones.

Contribute

Fork & pull request.

Have a question?

Ask at Stack Overflow, make sure to use the apiblueprint tag.

Alternatively, mention @apiblueprint. if you are a contributor, check out the API Blueprint Developers Discussion Group as well as the Issues Page.

License

MIT License. See the LICENSE file.

Blackshawk/api-blueprint