Skip to content

Instantly share code, notes, and snippets.

@JoshuaEstes
Created September 8, 2014 21:48
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save JoshuaEstes/d565918081ebc81ec7b7 to your computer and use it in GitHub Desktop.
Save JoshuaEstes/d565918081ebc81ec7b7 to your computer and use it in GitHub Desktop.

Introduction

Purpose

Requirements

Terminology

URL = "https:" "//" host [ ":" port ] [ abs_path [ "?" query ]]

Authentication

Authorization

Resources

GET /articles/1
HOST api.example.org
HTTP/1.1 200 OK

{
    "id": "<string>",
    "content": "<string>",
    "published": <boolean>,
    "_links": {
        "self": { "href": "/atricles/1" }
    }
}

HTTP Methods

OPTIONS

GET

HEAD

POST

PUT

DELETE

TRACE

HTTP Headers

Versioning

Sorting

GET /articles?sort=publishedAt
HOST api.example.org
HTTP/1.1 200 OK

[
    {
        "id": "<string>",
        "content": "<string>",
        "published": <boolean>,
        "publishedAt": "<DateTime>",
        "_links": {
            "self": { "href": "/atricles/1" }
        }
    }
]

Filtering

GET /articles?published=true
HOST api.example.org
HTTP/1.1 200 OK

[
    {
        "id": "<string>",
        "content": "<string>",
        "published": <boolean>,
        "publishedAt": "<DateTime>",
        "_links": {
            "self": { "href": "/atricles/1" }
        }
    }
]

Pagination

GET /articles?page=1&perPage=10
HOST api.example.org
HTTP/1.1 200 OK

[
    {
        "id": "<string>",
        "content": "<string>",
        "published": <boolean>,
        "publishedAt": "<DateTime>",
        "_links": {
            "self": { "href": "/atricles/1" }
            "next": { "href": "/articles?page=2&perPage=10" }
        }
    }
]

Limiting Fields Returned

GET /articles?fields=id,content&published=true
HOST api.example.org
HTTP/1.1 200 OK

[
    {
        "id": "<string>",
        "content": "<string>",
        "_links": {
            "self": { "href": "/atricles/1" }
        }
    }
]

Rate Limiting

Errors

Status Codes

Response Style

  • Field names are all camelCase
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment