pkdevboxy / api-blueprint

API Blueprint

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": "",

    ...

[full listing]

It is 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 article if you are interested in using API Blueprint in your tool chain.

Learn more

• API Blueprint Tutorial
• API Blueprint Examples
• API Blueprint Glossary of Terms
• API Blueprint 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

Find about 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 on Twitter.

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.