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.
- Web API description language
- Pure Markdown
- Designed for humans
- Understandable by machines
- Open & free
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.
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.
Building tools for API Blueprint is possible thanks to its machine-friendly face:
{
"_version": "2.0",
"metadata": [],
"name": "",
"description": "",
...
}
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.
The media type for API Blueprint is text/vnd.apiblueprint+markdown
.
- Tutorial
- Examples
- Glossary of Terms
- API Blueprint Map
- Language Specification
- Tools working with API Blueprint
- API Blueprint reference parser – Snow Crash
- Snow Crash Bindings to other languages
- API Blueprint AST Serialization Media Types
- Developing tools for API Blueprint
Check out the API Blueprint Issues Page for planned features and issues discussion.
Fork & pull request.
Ask at Stack Overflow, make sure to use the apiblueprint
tag. Alternatively mention @apiblueprint on Twitter.
MIT License. See the LICENSE file.