API Title
Markdown 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.
Note List ¶
Note list description
-
Even
-
More
-
Markdown
Get NotesGET/notes
Get a list of notes.
Example URI
200
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#"
}
Create New NotePOST/notes
Create a new note using a title and an optional content body.
Example URI
with body
Headers
Content-Type: application/json
Body
{
"title": "My new note",
"body": "This is the body"
}
201
400
Headers
Content-Type: application/json
Body
{
"error": "Invalid title"
}
without body
Headers
Content-Type: application/json
Body
{
"title": "My new note"
}
201
400
Headers
Content-Type: application/json
Body
{
"error": "Invalid title"
}
Note ¶
Note description
Get NoteGET/notes/{id}{?body}
Get a single note.
Example URI
- id
string
(required) Example: 68a5sdf67The note ID
- body
boolean
(required) Example: falseSet to
false
to exclude note body content.
200
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#"
}
404
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.
Example URI
- id
string
(required) Example: 68a5sdf67The note ID
Headers
Content-Type: application/json
Body
{
"title": "Grocery List (Safeway)"
}
200
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#"
}
404
Headers
Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms
Body
{
"error": "Note not found"
}
delete body
Headers
Content-Type: application/json
Body
{
"body": ""
}
200
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#"
}
404
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
Example URI
- id
string
(required) Example: 68a5sdf67The note ID
204
404
Headers
Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms
Body
{
"error": "Note not found"
}
Users ¶
Group description
User List ¶
A list of users
Get usersGET/users{?name,joinedBefore,joinedAfter,sort,limit}
Get a list of users. Example:
https://api.mywebsite.com/users?sort=joined&limit=5
Example URI
- 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
200
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}"
}
}
}
}