Back to top

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
  1. A list

  2. Of items

  3. Can be

  4. 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 Notes
GET/notes

Get a list of notes.

Example URI

GET https://api.example.com/notes
Response  200
HideShow
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 Note
POST/notes

Create a new note using a title and an optional content body.

Example URI

POST https://api.example.com/notes
Request  with body
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "My new note",
  "body": "This is the body"
}
Response  201
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Invalid title"
}
Request  without body
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "My new note"
}
Response  201
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Invalid title"
}

Note

Note description

Get Note
GET/notes/{id}{?body}

Get a single note.

Example URI

GET https://api.example.com/notes/id?body=false
URI Parameters
HideShow
id
string (required) Example: 68a5sdf67

The note ID

body
boolean (required) Example: false

Set to false to exclude note body content.

Response  200
HideShow
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#"
}
Response  404
HideShow
Headers
Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms
Body
{
  "error": "Note not found"
}

Update a Note
PUT/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

PUT https://api.example.com/notes/id
URI Parameters
HideShow
id
string (required) Example: 68a5sdf67

The note ID

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "Grocery List (Safeway)"
}
Response  200
HideShow
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#"
}
Response  404
HideShow
Headers
Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms
Body
{
  "error": "Note not found"
}
Request  delete body
HideShow
Headers
Content-Type: application/json
Body
{
  "body": ""
}
Response  200
HideShow
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#"
}
Response  404
HideShow
Headers
Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms
Body
{
  "error": "Note not found"
}

Delete a Note
DELETE/notes/{id}

Delete a single note

Example URI

DELETE https://api.example.com/notes/id
URI Parameters
HideShow
id
string (required) Example: 68a5sdf67

The note ID

Response  204
Response  404
HideShow
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 users
GET/users{?name,joinedBefore,joinedAfter,sort,limit}

Get a list of users. Example:

https://api.mywebsite.com/users?sort=joined&limit=5

Example URI

GET https://api.example.com/users?name=alice&joinedBefore=2011-01-01&joinedAfter=2011-01-01&sort=joined&limit=25
URI Parameters
HideShow
name
string (optional) Example: alice

Search for a user by name

joinedBefore
string (optional) Example: 2011-01-01

Search by join date

joinedAfter
string (optional) Example: 2011-01-01

Search by join date

sort
string (optional) Default: name Example: joined

Which field to sort by

Choices: name joined -joined age -age location -location plan -plan

limit
integer (optional) Default: 10 Example: 25

The maximum number of users to return, up to 50

Response  200
HideShow
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}"
      }
    }
  }
}

Tags and Tagging Long Title

Get or set tags on notes

Resource

GET/tags

Get a list of bars

Example URI

GET https://api.example.com/tags
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  "tag1",
  "tag2",
  "tag3"
]

Get one tag

Get a single tag

GET/tags/{id}

Example URI

GET https://api.example.com/tags/id
URI Parameters
HideShow
id
string (required) 

Unique tag identifier

Response  200

Generated by aglio on 11 Nov 2015