Apiary supports multiple API Description formats—API Blueprint and Swagger, but which one is right for you?

Both formats are open-sourced and have great community and tooling built around them.

Both should allow you to describe a broad set of API architectures with design-first approach. Swagger comes with tools to generate a description from code. API Blueprint syntax makes it easier to describe hypermedia/REST APIs.

If you are new to API Description world, we recommend to start with API Blueprint. See API Blueprint tutorial for a quickstart.

API Blueprint and Swagger examples

Here we have a simple API with 1 endpoint and 2 possible actions described in both API Blueprint and Swagger.

FORMAT: 1A
HOST: http://polls.apiblueprint.org/

# Polls API Blueprint

Polls is a simple API allowing consumers to view polls and vote in them.

## Questions Collection [/questions]

### List All Questions [GET]

+ Response 200 (application/json)

        [
            {
                "question": "Favourite programming language?",
                "published_at": "2015-08-05T08:40:51.620Z",
                "choices": [
                    {
                        "choice": "Swift",
                        "votes": 2048
                    }, {
                        "choice": "Python",
                        "votes": 1024
                    }, {
                        "choice": "Objective-C",
                        "votes": 512
                    }, {
                        "choice": "Ruby",
                        "votes": 256
                    }
                ]
            }
        ]

### Create a New Question [POST]

You may create your own question using this action. It takes a JSON
object containing a question and a collection of answers in the
form of choices.

+ Request (application/json)

        {
            "question": "Favourite programming language?",
            "choices": [
                "Swift",
                "Python",
                "Objective-C",
                "Ruby"
            ]
        }

+ Response 201 (application/json)

    + Headers

            Location: /questions/2

    + Body

            {
                "question": "Favourite programming language?",
                "published_at": "2015-08-05T08:40:51.620Z",
                "choices": [
                    {
                        "choice": "Swift",
                        "votes": 0
                    }, {
                        "choice": "Python",
                        "votes": 0
                    }, {
                        "choice": "Objective-C",
                        "votes": 0
                    }, {
                        "choice": "Ruby",
                        "votes": 0
                    }
                ]
            }

swagger: '2.0'
info:
  title: Polls Swagger
  description: Polls is a simple API allowing consumers to view polls and vote in them.
  version: "8234aab51481d37a30757d925b7f4221a659427e"
host: polls.apiblueprint.org
schemes:
  - https
paths:
  /questions:
    x-summary: Questions Collection
    x-description: ''
    get:
      summary: List all questions
      responses:
        200:
          description: 'List'
          examples:
            application/json:
              - question: "Favourite programming language?"
                published_at: "2015-08-05T08:40:51.620Z"
                choices:
                  - choice: "Swift"
                    votes: 2048
                  - choice: "Python"
                    votes: 1024
                  - choice: "Objective-C"
                    votes: 512
                  - choice: "Ruby"
                    votes: 256
    post:
      summary: Create a New Question
      description: You may create your own question using this action. It takes a JSON object containing a question and a collection of answers in the form of choices.
      responses:
        201:
          description: 'Created'
          examples:
            application/json:
              question: "Favourite programming language?"
              published_at: "2014-11-11T08:40:51.620Z"
              choices:
                - choice: "Swift"
                  votes: 0
                - choice: "Python"
                  votes: 0
                - choice: "Objective-C"
                  votes: 0
                - choice: "Ruby"
                  votes: 0
Was this page useful?
Thank you for the feedback!
What went wrong?