Skip to content

Instantly share code, notes, and snippets.

@harlanhaskins

harlanhaskins/apidoc.md

Created February 4, 2015 02:42
Show Gist options
  • Save harlanhaskins/11d8851c76bcedd5ac01 to your computer and use it in GitHub Desktop.
Save harlanhaskins/11d8851c76bcedd5ac01 to your computer and use it in GitHub Desktop.
Download ZIP
apidoc
Raw
apidoc.md

Quotes

A web API for quotes.

Dependencies

This project requires PostgreSQL and these python dependencies:

  • flask
  • peewee
  • py-bcrypt
  • pyOpenSSL
  • psycopg2
  • argparse

You can install all dependencies with this:

pip install flask peewee py-bcrypt pyOpenSSL psycopg2 argparse

Endpoints

Method Endpoint Description
POST /login Signs on as user
GET /me Returns information about current signed in user
PUT /me Modifies information about current signed in user
DELETE /me Deletes signed in user
GET /users Returns all users registered
POST /users Creates new user
GET /users/:id Returns the user with :id
GET /quotes Gets all quotes
POST /quotes Creates a quote
GET /quotes/:id Gets quote with :id
PUT /quotes/:id Modifies quote with :id
DELETE /quotes/:id Removes quote with :id
GET /quotes/:id/comments Gets the quote with :id's comments
PUT /quotes/:id/comments Modifies quote with :id's comments
DELETE /quotes/:id/comments/:id Removes comment with :id
GET /tags Gets all tags
GET /graph Gets graphing data
GET /api_key Gets the API Key for a user
POST /api_key Creates an API Key for a user
DELETE /api_key Removes an API Key for a user

Authentication

All requests except login must contain the header Authentication which contains a token returned by the /login endpoint.

POST to /login

Example request body:

{
  "username": "frenchie4111",
  "password": "michael9"
}

Example response:

{
  "token": "$2a$12$jGWCcEkXjCWE/v82tzJKkueopvVd86CsLjnIvLDB0NLJwVnWnX6VG",
  "user": {
    "email": "harlan@harlanhaskins.com",
    "first_name": "Harlan",
    "id": 1,
    "last_name": "Haskins",
    "username": "hhaskins"
  }
}

More information

GET /me

Returns information about current signed in user

Example response

{
  "email": "gr4nny5m1th@aol.com",
  "first_name": "Gertrude",
  "id": 1,
  "last_name": "Smith",
  "username": "gr4nny5m1th"
}

PUT /me

Modifies information about current signed in user

Example request

PUT to /me

{
  "password": "michael94"
}

Example response

{
  "success": true,
  "message": "User updated successfully."
}

DELETE /me

Deletes signed in user. This also removes all associated quotes and auth tokens

Example request

DELETE to /me

Example Response

{
  "success": true,
  "message": "User deleted successfully."
}

GET /users

Returns list of all users registered on server

Options /users?option=optionValue

Option Description
username Gets user with username
id Gets user with id
email Gets user with email
first_name Gets users with first_name
last_name Gets users with last_name

Example Response:

GET to /users

[
  {
    "email": "gr4nny5m1th@aol.com",
    "first_name": "Gertrude",
    "id": 1,
    "last_name": "Smith",
    "username": "gr4nny5m1th"
  },
  {
    "email": "70mj0n35@yahoo.com",
    "first_name": "Thomas",
    "id": 2,
    "last_name": "Jones",
    "username": "70mj0n35"
  }
]

POST /users

Creates a new user

Example request body:

{
  "username": "kocsenc",
  "password": "unicorn",
  "first_name": "Kocsen",
  "last_name": "Chung"
  "email": "kocsenc@hotmail.com"
}

Example response

{
  "success": true,
  "user": {
    "email": "kocsen+nospam@gmail.com",
    "first_name": "Kocsen",
    "id": 5,
    "last_name": "Chung",
    "username": "kocsenc"
  }
}

GET /quotes

Options /quotes?option=optionValue

Option Description
actor Get quotes for given actor
submitter Get filters created by given user
after Gets all quotes created after given date
before Gets all quotes created before given date

Example Request

GET to /quotes?actor=3

Example response

[
    {
        id: 1,
        creator: 1,
        actor: 3,
        description: "Kocsen stated: First name DICK last name SIN",
        severity: 5,
        created: 1403887464989,
        updated: 1403887464989,
        tags: ["funny", "vulgar"]
    },
    {
        id: 2,
        creator: 2,
        actor: 3,
        description: "Used two toilet cover papers at one time",
        severity: 5,
        created: 1403887464989,
        updated: 1403887464989,
        tags: ["funny"]
    }
]

POST /quotes

id, creator, created_at and updated_at are all created server side on insert When a quote is deleted, all associated rankings are to be deleted.

Example request

{
    actor: 2,
    description: "Made fun of my mommy",
    severity: 5,
    tags: ["funny", "loud"]
}

Example response

{
    status: "created",
    id: 17
}

PUT /quotes/:id

Updates a quote. Only the quote's creator can update it.

Example request

PUT to /quotes/17

{
    description: "Made fun of my daddy"
}

Example response

{
    status: "updated",
    id: 17
}

DELETE /quotes/:id

Deletes a quote. Only the quote's creator can delete it.

Example request

DELETE to /quotes/:id

Example response

{
    status: "deleted"
}

If you wish to remove a tag from a quote you can do it as follows:

Example request

DELETE to /quotes/17

{
    tags: ["funny"]
}

Example Response

{
    status: "deleted"
}

This would remove the tag with the name "funny" from the quote with id 17

GET /ratings

Gets all ratings. Can be filtered to only receive ratings for given quote

Options /ratings?option=optionValue

Option Description
quote Get ratings for given quote
submitter Get ratings for given submitter
stars Gets ratings with given score

Example request

GET to /ratings?quote=17

Example response

[
    {
        id: 17,
        quote: 17,
        submitter: 1,
        stars: 5
    },
    {
        id: 21,
        quote: 17,
        submitter: 3,
        stars: 2
    }
]

POST /ratings

Creates a rating. Submitter is automatically resolved with HRV-Token

Example request

{
    quote: 17,
    rating: 1
}

Example response

{
    status: "created",
    id: 22
}

PUT /ratings/:id

Modifies a rating. Ratings can only be modified by their creator

Example request

PUT to /ratings/22

{
    rating: 3
}

Example response

{
    status: "updated",
    id: 22
}

DELETE /ratings/:id

Deletes rating with id. Ratings can only be deleted by their creator

Example request

DELETE to /ratings/22

Example response

{
    status: "deleted"
}

GET /tags

Returns list of all tags

Example response

[
    "funny",
    "vulgar"
]

GET /graph

Returns graphing data.

Options /graph?option=value

Option Description
api_key The user's assigned API key
users A comma separated list of users
client The specified graphing client

Example response (client=statusboard)

{
    "graph": {
        "datasequences": [
            {
                "datapoints": [
                    {
                        "value": 0,
                        "title": "Monday"
                    },
                    {
                        "value": 0,
                        "title": "Tuesday"
                    },
                    {
                        "value": 0,
                        "title": "Wednesday"
                    },
                    {
                        "value": 0,
                        "title": "Thursday"
                    },
                    {
                        "value": 1,
                        "title": "Friday"
                    }
                ],
                "title": "John"
            },
            {
                "datapoints": [
                    {
                        "value": 0,
                        "title": "Monday"
                    },
                    {
                        "value": 0,
                        "title": "Tuesday"
                    },
                    {
                        "value": 0,
                        "title": "Wednesday"
                    },
                    {
                        "value": 0,
                        "title": "Thursday"
                    },
                    {
                        "value": 0,
                        "title": "Friday"
                    }
                ],
                "title": "Jimmy"
            }
        ],
        "total": true,
        "refreshEveryNSeconds": 60,
        "title": "HR quotes"
    }
}

GET /api_key

Returns the API key associated with a user.

Example response

{
    "key": "$2a$12$jGfCcEkXjCWE/v82tzJKkueopvVd86CsLjnIvLDB0NLJwVnWnX6VG",
    "user": {
      "email": "harlan@harlanhaskins.com",
      "first_name": "Harlan",
      "id": 1,
      "last_name": "Haskins",
      "username": "hhaskins"
    }
}

POST /api_key

Requests a new key from the system.

Example response

{
    "key": "$2a$12$jGfCcEkXjCWE/v82tzJKkueopvVd86CsLjnIvLDB0NLJwVnWnX6VG",
    "user": {
      "email": "harlan@harlanhaskins.com",
      "first_name": "Harlan",
      "id": 1,
      "last_name": "Haskins",
      "username": "hhaskins"
    }
}

DELETE /api_key

Requests a new key from the system.

Example response

{
    "key": "$2a$12$jGfCcEkXjCWE/v82tzJKkueopvVd86CsLjnIvLDB0NLJwVnWnX6VG",
    "user": {
      "email": "harlan@harlanhaskins.com",
      "first_name": "Harlan",
      "id": 1,
      "last_name": "Haskins",
      "username": "hhaskins"
    }
}

Errors

If a request fails for any reason, the error will be formatted as follows:

{
    status: "error",
    message: "Failed to Authenticate: Username or Password may be invalid"
}

Example request

DELETE to /api_key

Example response

{
    status: "deleted"
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment