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 API
description: "My API rocks! \n\n"
resourceGroups:
- name:
  description:
  resources:
  - uri: /message
    name:
    description:
    object:
    methods:
    - method: GET
      name:
      description:
      responses:
      - name: 200
        description:
        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.

empia / api-blueprint Goto Github PK

api-blueprint's Introduction