API Blueprint

Web API language

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

More Examples | I speak Hypermedia

What is API Blueprint?

API Blueprint is a lightweight, documentation-oriented domain specific language (DSL) for easily designing, building and documenting Web APIs. API Blueprint is a form of Markdown. It is easy to learn and read; perfect for comprehensive documentation but also for quick prototyping and collaboration.

TL;DR

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

Write, read and share

Prototype, design and document your API using a Markdown formatting of your liking.

Stay clean & tidy

# My API
My API rocks! ## GET /message- response 200 (application/json)
	{ "message": 'Hello World!' }

or go large

My API
======
My API rocks! GET /message
-------------+ Response 200 (application/json)
	{  "message": 'Hello World!' 	}

Parse & integrate

Parse your API Blueprint and integrate with your tools & frameworks.

Use a Command-line interface

JSON

$ snowcrash --format=json my_api.md

{"metadata": [],"name": "My API","description": "My API rocks! \n\n","resourceGroups": [{"name": "","description": "","resources": [{"uriTemplate": "/message","name": "","description": "","headers": [],"object": {"name": "","description": "","headers": [],"body": "","schema": ""},"methods": [{"method": "GET","name": "","description": "","headers": [],"requests": [],"responses": [{"name": "200","description": "","headers": [{"name": "Content-Type","value": "application/json"}],"body": "{ \"message\": 'Hello World!' } \n","schema": ""}]}]}]}]}

YAML

$ snowcrash --format=yaml my_api.md

name: My APIdescription: "My API rocks! \n\n"resourceGroups:
- name:
description:
resources:
- uri: /messagename:
description:
object:
methods:
- method: GETname:
description:
responses:
- name: 200description:
body: "{ "message": 'Hello World!' }\n"schema:
headers:
- Content-Type: application/json

Getting started

View examples

Start with the API Blueprint Tutorial or just browse the examples.

Get the API Blueprint Parser

Get Snow Crash – the Canonical API Blueprint Parser.

Or one of its bindings

Refer to the Snow Crash [bindings]((https://github.com/apiaryio/snowcrash#bindings).

• Node.js:Protagonist
• Ruby: none yet - we're looking for contributors
• Python: none yet - we're looking for contributors
• Java: none yet - we're looking for contributors
• PHP: none yet - we're looking for contributors

Have a question?

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

Alternatively, if you are a contributor, check out the API Blueprint Developers Discussion Group.

Version

• Actual version: Format 1A

What's next?

API Blueprint Roadmap

Refer to the API Blueprint Roadmap Wiki Page.

Brew Parser

not ready yet, work in progress

$ brew install snowcrash
$ snowcrash --help

License

MIT License. See the LICENSE file.