API Title
API Endpoint
https://api.example.comMarkdown formatted description.
Subtitle
Also Markdown formatted. This also includes automatic “smartypants” formatting – hooray!
“A quote from another time and place”
Another paragraph. Code sample:
Authorization: bearer 5262d64b892e8d4341000001
And some code with no highlighting:
Foo bar baz
-
A list
-
Of items
-
Can be
-
Very useful
Here is a table:
ID | Name | Description |
---|---|---|
1 | Foo | I am a foo. |
8 | Bar | I am a bar. |
15 | Baz | I am a baz. |
Extensions
Some non-standard Markdown extensions are also supported, such as this informational container, which can also contain formatting. Features include:
-
Informational block fenced with
::: note
and:::
-
Warning block fenced with
::: warning
and:::
-
[x]
and[ ]
-
Emoji support 😀 🚀 🍰 using
:smile:
(cheat sheet)
These extensions may change in the future as the CommonMark specification defines a standard extension syntax.
Included File
This is content that was included from another file! It’s easy, simply use include(filename)
in an HTML comment (<!-- include... -->
).
Included files can include other files as well, allowing you to structure your API documentation as you see fit. Since Markdown supports inline HTML, the files you include can be either Markdown or HTML.
Notes ¶
Group description (also with Markdown)
Important Info
Descriptions may also contain sub-headings and more Markdown.
Headers
Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms
Body
[
{
"id": 1,
"title": "Grocery list",
"body": "Buy milk"
}
]
Schema
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "Unique identifier"
},
"title": {
"type": "string",
"description": "Single line description"
},
"body": {
"type": "string",
"description": "Full description of the note which supports Markdown."
}
},
"required": [
"id",
"title"
]
},
"$schema": "http://json-schema.org/draft-04/schema#"
}
Get NotesGET/notes
Get a list of notes.
Headers
Content-Type: application/json
Body
{
"title": "My new note",
"body": "This is the body"
}
Headers
Content-Type: application/json
Body
{
"error": "Invalid title"
}
Headers
Content-Type: application/json
Body
{
"title": "My new note"
}
Headers
Content-Type: application/json
Body
{
"error": "Invalid title"
}
Create New NotePOST/notes
Create a new note using a title and an optional content body.
Note ¶
Note description
Headers
Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms
Body
{
"id": 1,
"title": "Grocery list",
"body": "Buy milk"
}
Schema
{
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "Unique identifier"
},
"title": {
"type": "string",
"description": "Single line description"
},
"body": {
"type": "string",
"description": "Full description of the note which supports Markdown."
}
},
"required": [
"id",
"title"
],
"$schema": "http://json-schema.org/draft-04/schema#"
}
Headers
Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms
Body
{
"error": "Note not found"
}
Get NoteGET/notes/{id}{?body}
Get a single note.
- id
string
(required) Example: 68a5sdf67The note ID
- body
boolean
(required) Example: falseSet to
false
to exclude note body content.
Headers
Content-Type: application/json
Body
{
"title": "Grocery List (Safeway)"
}
Headers
Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms
Body
{
"id": 1,
"title": "Grocery list",
"body": "Buy milk"
}
Schema
{
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "Unique identifier"
},
"title": {
"type": "string",
"description": "Single line description"
},
"body": {
"type": "string",
"description": "Full description of the note which supports Markdown."
}
},
"required": [
"id",
"title"
],
"$schema": "http://json-schema.org/draft-04/schema#"
}
Headers
Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms
Body
{
"error": "Note not found"
}
Headers
Content-Type: application/json
Body
{
"body": ""
}
Headers
Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms
Body
{
"id": 1,
"title": "Grocery list",
"body": "Buy milk"
}
Schema
{
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "Unique identifier"
},
"title": {
"type": "string",
"description": "Single line description"
},
"body": {
"type": "string",
"description": "Full description of the note which supports Markdown."
}
},
"required": [
"id",
"title"
],
"$schema": "http://json-schema.org/draft-04/schema#"
}
Headers
Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms
Body
{
"error": "Note not found"
}
Update a NotePUT/notes/{id}
Update a single note by setting the title and/or body.
Caution
If the value for title
or body
is null
or undefined
, then the corresponding value is not modified on the server. However, if you send an empty string instead then it will permanently overwrite the original value.
- id
string
(required) Example: 68a5sdf67The note ID
Headers
Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms
Body
{
"error": "Note not found"
}
Delete a NoteDELETE/notes/{id}
Delete a single note
- id
string
(required) Example: 68a5sdf67The note ID
Users ¶
Group description
User List ¶
A list of users
Headers
Content-Type: application/json
Body
[
{
"name": "alice",
"image": "http://example.com/alice.jpg",
"joined": "2013-11-01"
},
{
"name": "bob",
"image": "http://example.com/bob.jpg",
"joined": "2013-11-02"
}
]
Schema
{
"type": "array",
"maxItems": 50,
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"image": {
"type": "string"
},
"joined": {
"type": "string",
"pattern": "\\d{4}-\\d{2}-\\d{2}"
}
}
}
}
Get usersGET/users{?name,joinedBefore,joinedAfter,sort,limit}
Get a list of users. Example:
https://api.mywebsite.com/users?sort=joined&limit=5
- name
string
(optional) Example: aliceSearch for a user by name
- joinedBefore
string
(optional) Example: 2011-01-01Search by join date
- joinedAfter
string
(optional) Example: 2011-01-01Search by join date
- sort
string
(optional) Default: name Example: joinedWhich field to sort by
Choices:
name
joined
-joined
age
-age
location
-location
plan
-plan
- limit
integer
(optional) Default: 10 Example: 25The maximum number of users to return, up to
50
Headers
Content-Type: application/json
Body
[
"tag1",
"tag2",
"tag3"
]
Generated by aglio on 11 Nov 2015