NAV
http

Introduction

Welcome to rails tutorial API. The implementation of the API can be found here. Using this API an Ember application is also built, found here.

The following documents the V1 API.

Overview

General Notes

You are encouraged to always provide a valid user-agent string.

Current Version

The current version of API is V1. The version is defined on the resource, thus reflecting the resource version and not in the Accept header.

GET /api/v1/resource HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Host: rails-tutorial-api.heroku.com

DateTimes representations

All date/time representations are on ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ The returned timezone is UTC.

Client Errors

HTTP/1.1 400 Bad Request
Content-Length: 35
{
  "message":"Problems parsing JSON"
}
HTTP/1.1 422 Unprocessable Entity
Content-Length: 149
{
  "errors": [
    {
      "field": "title",
      "message": "title cannot be blank"
    },
    {
      "field": "description",
      "message": "description must be less than 1000 characters"
    },
  ]
}
HTTP/1.1 401 Unprocessable Entity
Content-Length: 149
{
  "message": "Authentication Failed",
}
HTTP/1.1 403 Unprocessable Entity
Content-Length: 149
{
  "message": "Not authorized action for that resource",
}
HTTP/1.1 500 Unprocessable Entity
Content-Length: 149
{
  "message": "Something went terribly wrong here. Open a github issue :)",
}

The client errors are pretty basic, yet helpful.

Error Code Meaning
400 Bad Request – You have a critical error on your request, like bad JSON representation
401 Unauthorized – You try to access a protected resource without providing authentication credentials or with wrong credentials
403 Forbidden – You try to access or act on a protected resource but your credentials that you provide do not authorize your action for that resource.
404 Not Found – The specified kitten could not be found
405 Method Not Allowed – You tried to access a kitten with an invalid method
406 Not Acceptable – You requested a format that isn’t json
422 lalala – Your request is understood but you miss a required param, or part of your json is in wrong format (like sending an date object in an integer param)
429 Too Many Requests – Slown down! Follow the rate limits!
500 Internal Server Error – Something went terribly wrong, open a gihub issue :)

Authentication

POST /api/v1/sessions HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Host: rails-tutorial-api.heroku.com
{
  "user": {
    "email": "example@railstutorial.org",
    "password": "123123123"
  }
}
HTTP/1.1 200 OK
Content-Type: application/json
{
  "token": "TnQfBY1S/aMdO46sUfXx8mkPa4yxawqgaqVlD2YNzj19QlGI02eFIpoj9YaBtXm3efQZt5oXIQ6DpBw9gvuVGA==",
  "user_email": "example@railstutorial.org",
  "user_id": 1
}

In order to be able to act on behalf of a user, you must first retrieve her token via the sessions endpoint.

Authorization

GET /api/v1/resource HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Host: rails-tutorial-api.heroku.com
Authorization: Token token="TnQfBY1S/aMdO46sUfXx8mkPa4yxawqgaqVlD2YNzj19QlGI02eFIpoj9YaBtXm3efQZt5oXIQ6DpBw9gvuVGA==", user_email="example@railstutorial.org"
HTTP/1.1 200 OK
Content-Type: application/json
{
  "user":{
    "id":1,
    "email":"example@railstutorial.org",
    "name":"Example Use",
    "activated":true,
    "created_at":"2015-01-13T20:35:24Z",
    "updated_at":"2015-02-09T19:47:36Z"
  }
}

You can authenticate in the API by providing the user’s token and email in the Authorization header.

Pagination

GET /api/v1/resource?page=2&per_page=100 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/vnd.travis-ci.2+json
Host: rails-tutorial-api.heroku.com

Requests that return multiple items will be paginated to 30 items by default. You can specify further pages with the ?page parameter. For some resources, you can also set a custom page size up to 100 with the ?per_page parameter.

Rate Limiting

HTTP/1.1 200 OK
Date: Mon, 01 Jul 2013 17:27:06 GMT
Status: 200 OK
X-Ratelimit-Limit: 100000
X-Ratelimit-Remaining: 99994

You can check the returned HTTP headers of any API request to see your current rate limit status.

It should be noted that the rate limit is variable, depending on the server load. Please stay on the limits.

If you have abused the limits, you will receive a 429 error as described in the Client Errors

Cross Origin Resource Sharing

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin.

Meta Data

GET /api/v1/resources HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
HTTP/1.1 200 OK
Content-Length: 4567
{
  "resources": [
    {
      "attribute1":1,
      "attribute2":"test-attribute 1",
    },
    {
      "attribute1":2
      "attribute2":"test-attribute 2"
    }
  ],
  "meta":{
    "current_page":45,
    "next_page":46,
    "prev_page":44,
    "total_pages":53,
    "total_count":105
  }
}

In each GET request that acts upon resources, there is an extra field in the response under “meta” root element. It includes, the current requested page, next page, previous page, total pages and the total number of resources under the given params.

Other information

When requesting a list of resources, default sorting is descending by creation datetime.

For all collection endpoints, active_hash_relation has been used which means you have plenty options to filter

Users

List Users

GET /api/v1/users HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
HTTP/1.1 200 OK
Content-Length: 4567
{
  "users":[
    {
      "id":1,
      "email":"example-88@railstutorial.org",
      "name":"Kenna Ondricka",
      "activated":true,
      "created_at":"2015-01-13T20:35:47Z",
      "updated_at":"2015-02-02T22:09:50Z",
      "micropost_ids":[],
      "following_ids":[],
      "follower_ids":[]
    },
    {
      "id":1,
      "email":"example-89@railstutorial.org",
      "name":"Della Oberbrunner PhD",
      "activated":true,
      "created_at":"2015-01-13T20:35:47Z",
      "updated_at":"2015-02-02T22:09:50Z",
      "micropost_ids":[],
      "following_ids":[],
      "follower_ids":[]
    }
  ],
  "meta":{
    "current_page":1,
    "next_page":2,
    "prev_page":null,
    "total_pages":10,
    "total_count":300
  }
}

You can GET all users in /api/v1/users. You can filter by any attribute. More on the index micro-API here. It doesn’t require authentication.

Create a User

POST /api/v1/users HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json

{
  "user": {
    "email":"example-88@railstutorial.org",
    "name":"Kenna Ondricka",
  }
}
HTTP/1.1 200 OK
Content-Length: 4567
{
  "user": {
    "id":1,
    "email":"example-88@railstutorial.org",
    "name":"Kenna Ondricka",
    "activated":true,
    "created_at":"2015-01-13T20:35:47Z",
    "updated_at":"2015-02-02T22:09:50Z",
    "micropost_ids":[],
    "following_ids":[],
    "follower_ids":[]
  }
},

You can create a new user sending a POST to /api/v1/users with the necessary attributes. A user object should at least include, an email, a password It doesn’t require authentication.

Show a User

GET /api/v1/users/1 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
HTTP/1.1 200 OK
Content-Length: 4567
{
  "user": {
    "id":1,
    "email":"example-88@railstutorial.org",
    "name":"An updated name",
    "activated":true,
    "created_at":"2015-01-13T20:35:47Z",
    "updated_at":"2015-02-02T22:09:50Z",
    "micropost_ids":[],
    "following_ids":[],
    "follower_ids":[]
  }
},

You can retrieve a user’s info by sending a GET request to /api/v1/users/{id}.

Update a User

PUT /api/v1/users/1 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
{
  "user": {
    "name":"An updated name",
  }
}
HTTP/1.1 200 OK
Content-Length: 4567
{
  "user": {
    "id":1,
    "email":"example-88@railstutorial.org",
    "name":"An updated name",
    "activated":true,
    "created_at":"2015-01-13T20:35:47Z",
    "updated_at":"2015-02-02T22:09:50Z",
    "micropost_ids":[],
    "following_ids":[],
    "follower_ids":[]
  }
},

You can update a user’s attributes by sending a PUT request to /api/v1/users/{id} with the necessary attributes.

Destroy a User

DELETE /api/v1/users/1 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
HTTP/1.1 200 OK
Content-Length: 4567
{
  "user": {
    "id":1,
    "email":"example-88@railstutorial.org",
    "name":"Kenna Ondricka",
    "activated":true,
    "created_at":"2015-01-13T20:35:47Z",
    "updated_at":"2015-02-02T22:09:50Z",
    "micropost_ids":[],
    "following_ids":[],
    "follower_ids":[]
  }
},

You get back the deleted user.

Microposts

List Microposts

GET /api/v1/microposts HTTP/1.1
Micropost-Agent: MyClient/1.0.0
Accept: application/json
HTTP/1.1 200 OK
Content-Length: 4567
{
  "microposts":[
    {
      "id":1,
      "content":"A simple micropost",
      "picture": null,
      "created_at":"2015-01-13T20:35:47Z",
      "updated_at":"2015-02-02T22:09:50Z",
      "user_id":1
    },
    {
      "id":2,
      "content":"Another simple micropost",
      "picture": null,
      "created_at":"2015-01-13T20:35:47Z",
      "updated_at":"2015-02-02T22:09:50Z",
      "user_id":1
    }
  ],
  "meta":{
    "current_page":1,
    "next_page":2,
    "prev_page":null,
    "total_pages":10,
    "total_count":300
  }
}

You can GET all microposts in /api/v1/microposts. user_id is required. You can filter by any attribute. More on the index micro-API here. Also, if you pass in feed=true then you get the feed for user with user_id. It doesn’t require authentication.

Create a Micropost

POST /api/v1/microposts HTTP/1.1
Micropost-Agent: MyClient/1.0.0
Accept: application/json

{
  "micropost": {
    "content":"A simple micropost",
    "user_id":1
  }
}
HTTP/1.1 200 OK
Content-Length: 4567
{
  "micropost": {
    "id":1,
    "content":"A simple micropost",
    "picture": null,
    "created_at":"2015-01-13T20:35:47Z",
    "updated_at":"2015-02-02T22:09:50Z",
    "user_id":1
  }
},

You can create a new micropost sending a POST to /api/v1/microposts with the necessary attributes. A micropost object should at least include, content and a user_id. A user can create only micropost with her own user_id.

Show a Micropost

GET /api/v1/microposts/1 HTTP/1.1
Micropost-Agent: MyClient/1.0.0
Accept: application/json
HTTP/1.1 200 OK
Content-Length: 4567
{
  "micropost": {
    "id":1,
    "content":"A simple micropost",
    "picture": null,
    "created_at":"2015-01-13T20:35:47Z",
    "updated_at":"2015-02-02T22:09:50Z",
    "user_id":1
  }
},

You can retrieve a micropost’s info by sending a GET request to /api/v1/microposts/{id}.

Update a Micropost

PUT /api/v1/microposts/1 HTTP/1.1
Micropost-Agent: MyClient/1.0.0
Accept: application/json
{
  "micropost": {
    "content":"An updated content",
  }
}
HTTP/1.1 200 OK
Content-Length: 4567
{
  "micropost": {
    "id":1,
    "content":"An updated content",
    "picture": null,
    "created_at":"2015-01-13T20:35:47Z",
    "updated_at":"2015-02-02T22:09:50Z",
    "user_id":1
  }
},

You can update a micropost’s attributes by sending a PUT request to /api/v1/microposts/{id} with the necessary attributes.

Destroy a Micropost

DELETE /api/v1/microposts/1 HTTP/1.1
Micropost-Agent: MyClient/1.0.0
Accept: application/json
HTTP/1.1 200 OK
Content-Length: 4567
{
  "micropost": {
    "id":1,
    "content":"An updated content",
    "picture": null,
    "created_at":"2015-01-13T20:35:47Z",
    "updated_at":"2015-02-02T22:09:50Z",
    "user_id":1
  }
},

You get back the deleted micropost.

Followers

List Followers for a specific User

GET /api/v1/users/1/links/followers HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
HTTP/1.1 200 OK
Content-Length: 4567
{
  "following":[
    {
      "id":1,
      "email":"example-88@railstutorial.org",
      "name":"Kenna Ondricka",
      "activated":true,
      "created_at":"2015-01-13T20:35:47Z",
      "updated_at":"2015-02-02T22:09:50Z",
      "micropost_ids":[],
      "following_ids":[],
      "follower_ids":[]
    },
    {
      "id":1,
      "email":"example-89@railstutorial.org",
      "name":"Della Oberbrunner PhD",
      "activated":true,
      "created_at":"2015-01-13T20:35:47Z",
      "updated_at":"2015-02-02T22:09:50Z",
      "micropost_ids":[],
      "following_ids":[],
      "follower_ids":[]
    }
  ],
  "meta":{
    "current_page":1,
    "next_page":2,
    "prev_page":null,
    "total_pages":10,
    "total_count":300
  }
}

You can GET all users followers in /api/v1/users/:id/followers. It doesn’t require authentication.

Update Followers for a User

PUT /api/v1/users/1/followers HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json

{
  "follower_ids": [2,3,4,5,6,7]
}
HTTP/1.1 204 OK
Content-Length: 4567

You can update a user’s followers sending a POST to /api/v1/users/:id/followers with the follower_ids.

Get a user’s follower

GET /api/v1/users/1/followers/2 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
HTTP/1.1 204 OK

It actually helps you figure out if a user if a follower for another user or not. If the follower you check is not a follower to the user then you get back a 404.

Create a Follower for a User

POST /api/v1/users/1/followers/2 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
HTTP/1.1 200 OK

If the follower is already there you get back a 304.

Destroy a User

DELETE /api/v1/users/1/links/followers/2 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json

If the follower has already been deleted or was never there you get back a 304.

Followings

List Followings for a specific User

GET /api/v1/users/1/links/followings HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
HTTP/1.1 200 OK
Content-Length: 4567
{
  "following":[
    {
      "id":1,
      "email":"example-88@railstutorial.org",
      "name":"Kenna Ondricka",
      "activated":true,
      "created_at":"2015-01-13T20:35:47Z",
      "updated_at":"2015-02-02T22:09:50Z",
      "micropost_ids":[],
      "following_ids":[],
      "follower_ids":[]
    },
    {
      "id":1,
      "email":"example-89@railstutorial.org",
      "name":"Della Oberbrunner PhD",
      "activated":true,
      "created_at":"2015-01-13T20:35:47Z",
      "updated_at":"2015-02-02T22:09:50Z",
      "micropost_ids":[],
      "following_ids":[],
      "follower_ids":[]
    }
  ],
  "meta":{
    "current_page":1,
    "next_page":2,
    "prev_page":null,
    "total_pages":10,
    "total_count":300
  }
}

You can GET all users followings in /api/v1/users/:id/followings. It doesn’t require authentication.

Update Followings for a User

PUT /api/v1/users/1/followings HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json

{
  "following_ids": [2,3,4,5,6,7]
}
HTTP/1.1 204 OK
Content-Length: 4567

You can update a user’s followings sending a POST to /api/v1/users/:id/followings with the following_ids.

Get a user’s following

GET /api/v1/users/1/followings/2 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
HTTP/1.1 204 OK

It actually helps you figure out if a user if a following for another user or not. If the following you check is not a following to the user then you get back a 404.

Create a Follower for a User

POST /api/v1/users/1/followings/2 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
HTTP/1.1 200 OK

If the following is already there you get back a 304.

Destroy a User

DELETE /api/v1/users/1/links/followings/2 HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json

If the following has already been deleted or was never there you get back a 304.