API proposal.md

Create New CatVideo

Rationale

because cats are awesome, i want to save all videos i can find about them

Request

Url

POST https://myservice.com/api/cat_videos

Headers

Accept: application/json, application/vnd.myservice+json; version=2
Authorization: Bearer asdf987asd0f987a0s9d8f...

Body/Parameters

{
  "cat_video": {
    "name": "cat falling sleep",
    "comment": "aaawww",
    "url": "https://youtube.com/W/OIYOIUyO"
  }
}

Response

Status Code: 201 Created

Headers

Content-Type: application/json
Etag: \W"halskjdho8733halk82"

Body

{
  "id": 345,
  "created_at": "2015-06-10T12:30:42+01:00",
  "updated_at": "2015-06-10T12:30:42+01:00",
  "name": "cat falling sleep",
  "comment": "aaawww",
  "url": "https://youtube.com/W/OIYOIUyO"
}

Error Cases

Some of the error cases that can occur, with causes are:

• 400 Bad Request: when the user doesn't send the cat_video object
• 422 Unprocessable Entity:
  • when name or url are missing for cat video
  • when url is already on the system
• 401 Unauthorized: the token is invalid or expired
• 403 Forbidden: you don't have permissions to add videos of cats anymore