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