Choosing the right format
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.
- Swagger is YAML (or JSON) format, with focus to be easy to parse and has wide options of extensions and integrations.
- API Blueprint comes with syntax close to Markdown, MSON and full support of all Apiary tooling and open-source tooling.
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: https://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