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 https://api.example.com/notes
Responses200
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 Notes
GET/notes

Get a list of notes.


POST https://api.example.com/notes
Requestswith bodywithout body
Headers
Content-Type: application/json
Body
{
  "title": "My new note",
  "body": "This is the body"
}
Responses201400
This response has no content.
Headers
Content-Type: application/json
Body
{
  "error": "Invalid title"
}
Headers
Content-Type: application/json
Body
{
  "title": "My new note"
}
Responses201400
This response has no content.
Headers
Content-Type: application/json
Body
{
  "error": "Invalid title"
}

Create New Note
POST/notes

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


Note

Note description

GET https://api.example.com/notes/id?body=false
Responses200404
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 Note
GET/notes/{id}{?body}

Get a single note.

URI Parameters
HideShow
id
string (required) Example: 68a5sdf67

The note ID

body
boolean (required) Example: false

Set to false to exclude note body content.


PUT https://api.example.com/notes/id
Requestsexample 1delete body
Headers
Content-Type: application/json
Body
{
  "title": "Grocery List (Safeway)"
}
Responses200404
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": ""
}
Responses200404
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 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.

URI Parameters
HideShow
id
string (required) Example: 68a5sdf67

The note ID


DELETE https://api.example.com/notes/id
Responses204404
This response has no content.
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

URI Parameters
HideShow
id
string (required) Example: 68a5sdf67

The note ID


Users

Group description

User List

A list of users

GET https://api.example.com/users?name=alice&joinedBefore=2011-01-01&joinedAfter=2011-01-01&sort=joined&limit=25
Responses200
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 users
GET/users{?name,joinedBefore,joinedAfter,sort,limit}

Get a list of users. Example:

https://api.mywebsite.com/users?sort=joined&limit=5
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


Tags and Tagging Long Title

Get or set tags on notes

Resource

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

GET/tags

Get a list of bars


Get one tag

Get a single tag

GET https://api.example.com/tags/id
Responses200
This response has no content.

GET/tags/{id}

URI Parameters
HideShow
id
string (required) 

Unique tag identifier


Generated by aglio on 11 Nov 2015