API Reference

Did you find errors or missing information? Edit this page at app/views/pages/api_reference.html.md

---

Session

POST /api/session

Creates a new session using a third party auth provider token.

If a user associated to the access token doesn't exist, a new user will be created.

The response includes a Tomatoes API token that should be used to perform authenticated requests.

Supported providers:

• GitHub

Request

POST /api/session

Request content

{
  "provider": "github",
  "access_token": "348871aaaeec6e4fbf6506e609d71cca8d999e04"
}

Response

• 200 Ok
• 400 Bad Request, the selected provider is not supported
• 401 Unauthorized, the access token provided is not valid

Response content

{
  "token": "d994a295cf68342b99e3036827d3ef8a"
}

DELETE /api/session

Deletes all Tomatoes API active sessions for the current user.

Auth header example

Authorization: d994a295cf68342b99e3036827d3ef8a

Response

• 204 No Content
• 401 Unauthorized, invalid token

---

User

GET /api/user

Returns current user's data.

Auth header example

Authorization: d994a295cf68342b99e3036827d3ef8a

Response

• 200 Ok
• 401 Unauthorized, invalid token

Response content

{
  "id": "57f9c7f57c8402cc74b2cc5c",
  "name": "Giovanni Cappellotto",
  "email": null,
  "image": "https://avatars.githubusercontent.com/u/153842?v=3",
  "time_zone": null,
  "color": "#000000",
  "volume": 2,
  "ticking": false,
  "work_hours_per_day": null,
  "average_hourly_rate": null,
  "currency": "USD",
  "currency_unit": "$",
  "tomatoes_counters": {
    "day": 0,
    "week": 0,
    "month": 2
  },
  "authorizations": [
    {
      "provider": "github",
      "uid": "153842",
      "nickname": "potomak",
      "image": "https://avatars.githubusercontent.com/u/153842?v=3"
    }
  ],
  "created_at": "2016-10-09T04:30:45.300Z",
  "updated_at": "2016-10-09T04:30:45.300Z"
}

PUT/PATCH /api/user

Updates current user's attributes.

Auth header example

Authorization: d994a295cf68342b99e3036827d3ef8a

Request content

{
  "user": {
    "name": "Giovanni",
    "email": "giovanni@tomato.es",
    "image": "http://tomato.es/giovanni.png",
    "time_zone": "Europe/Rome",
    "color": "#00ccff",
    "work_hours_per_day": 8,
    "average_hourly_rate": 50,
    "currency": "USD",
    "volume": 1,
    "ticking": false
  }
}

Response

• 200 Ok
• 401 Unauthorized, invalid token
• 422 Unprocessable Entity, validation error

Successful response content

{
  "id": "57f9c7f57c8402cc74b2cc5c",
  "name": "Giovanni",
  "email": "giovanni@tomato.es",
  "image": "http://tomato.es/giovanni.png",
  "time_zone": "Europe/Rome",
  "color": "#00ccff",
  "volume": 1,
  "ticking": false,
  "work_hours_per_day": 8,
  "average_hourly_rate": 50,
  "currency": "USD",
  "currency_unit": "$",
  "tomatoes_counters": {
    "day": 0,
    "week": 0,
    "month": 2
  },
  "authorizations": [
    {
      "provider": "github",
      "uid": "153842",
      "nickname": "potomak",
      "image": "https://avatars.githubusercontent.com/u/153842?v=3"
    }
  ],
  "created_at": "2016-10-09T04:30:45.300Z",
  "updated_at": "2016-10-09T04:30:45.300Z"
}

---

Tomatoes

GET /api/tomatoes

Returns a list of current user's tomatoes.

The list of tomatoes is ordered by descending creation date and it's paginated. Each page contains 25 records, by default the first page is retuned, use the page parameter to get any other page in the range [1, total_pages].

Auth header example

Authorization: d994a295cf68342b99e3036827d3ef8a

Request parameters

• page a positive integer value to select a page in the range [1, total_pages]
• from a ISO 8601 date time, selects tomatoes where created_at is greater than or equals to the parameter value
• to a ISO 8601 date time, selects tomatoes where created_at is less than the parameter value

Response

• 200 Ok
• 401 Unauthorized, invalid token

Response content

{
  "tomatoes": [
    {
      "id": "57f9c9377c8402dd306d1c8b",
      "created_at": "2016-10-09T04:36:07.787Z",
      "updated_at": "2016-10-09T04:36:07.787Z",
      "tags": ["one", "two"]
    },
    {
      "id": "57f9c9187c8402dd306d1c88",
      "created_at": "2016-10-09T04:35:36.952Z",
      "updated_at": "2016-10-09T04:35:36.952Z",
      "tags": []
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 2
  }
}

GET /api/tomatoes/:id

Returns one of current user's tomatoes.

Auth header example

Authorization: d994a295cf68342b99e3036827d3ef8a

Response

• 200 Ok
• 401 Unauthorized, invalid token
• 404 Not Found

Response content

{
  "id": "57f9c9187c8402dd306d1c88",
  "created_at": "2016-10-09T04:35:36.952Z",
  "updated_at": "2016-10-09T04:35:36.952Z",
  "tags": ["one", "two"]
}

POST /api/tomatoes

Creates a new tomato.

Auth header example

Authorization: d994a295cf68342b99e3036827d3ef8a

Request content

{
  "tomato": {
    "tag_list": "one, two"
  }
}

Response

• 201 Created
• 401 Unauthorized, invalid token
• 422 Unprocessable Entity, validation error

Successful response content

{
  "id": "57f9c9187c8402dd306d1c88",
  "created_at": "2016-10-09T04:35:36.952Z",
  "updated_at": "2016-10-09T04:35:36.952Z",
  "tags": ["one", "two"]
}

Failure response content

{
  "base": ["Must not overlap saved tomaotes, please wait 24 minutes, 59 seconds"]
}

PUT/PATCH /api/tomatoes/:id

Updates one of current user's tomatoes.

Auth header example

Authorization: d994a295cf68342b99e3036827d3ef8a

Request content

{
  "tomato": {
    "tag_list": "one, two"
  }
}

Response

• 200 Ok
• 401 Unauthorized, invalid token
• 422 Unprocessable Entity, validation error

Successful response content

{
  "id": "57f9c9187c8402dd306d1c88",
  "created_at": "2016-10-09T04:35:36.952Z",
  "updated_at": "2016-10-09T04:35:36.952Z",
  "tags": ["one", "two"]
}

DELETE /api/tomatoes/:id

Deletes one of current user's tomatoes.

Auth header example

Authorization: d994a295cf68342b99e3036827d3ef8a

Response

• 204 No Content
• 401 Unauthorized, invalid token
• 404 Not Found

---

Projects

GET /api/projects

Returns a list of current user's projects.

The list of projects is ordered by descending creation date and it's paginated. Each page contains 25 records, by default the first page is retuned, use the page parameter to get any other page in the range [1, total_pages].

Auth header example

Authorization: d994a295cf68342b99e3036827d3ef8a

Request parameters

• page a positive integer value to select a page in the range [1, total_pages]
• tag_list a list of tags separated by commas

Response

• 200 Ok
• 401 Unauthorized, invalid token

Response content

{
  "projects": [
    {
      "id": "57f9c9377c8402dd306d1c8b",
      "name": "Web app",
      "created_at": "2016-10-09T04:36:07.787Z",
      "updated_at": "2016-10-09T04:36:07.787Z",
      "tags": ["one", "two"],
      "money_budget": 1200,
      "time_budget": 120
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 1
  }
}

GET /api/projects/:id

Returns one of current user's projects.

Auth header example

Authorization: d994a295cf68342b99e3036827d3ef8a

Response

• 200 Ok
• 401 Unauthorized, invalid token
• 404 Not Found

Response content

{
  "id": "57f9c9377c8402dd306d1c8b",
  "name": "Web app",
  "created_at": "2016-10-09T04:36:07.787Z",
  "updated_at": "2016-10-09T04:36:07.787Z",
  "tags": ["ruby", "acme"],
  "money_budget": 1200,
  "time_budget": 120
}

POST /api/projects

Creates a new project.

Auth header example

Authorization: d994a295cf68342b99e3036827d3ef8a

Request content

{
  "project": {
    "name": "Web app",
    "tag_list": "ruby, acme",
    "money_budget": 1200,
    "time_budget": 120
  }
}

Response

• 201 Created
• 401 Unauthorized, invalid token
• 422 Unprocessable Entity, validation error

Successful response content

{
  "id": "57f9c9377c8402dd306d1c8b",
  "name": "Web app",
  "created_at": "2016-10-09T04:36:07.787Z",
  "updated_at": "2016-10-09T04:36:07.787Z",
  "tags": ["ruby", "acme"],
  "money_budget": 1200,
  "time_budget": 120
}

Failure response content

{
  "name": ["can't be blank"]
}

PUT/PATCH /api/projects/:id

Updates one of current user's projects.

Auth header example

Authorization: d994a295cf68342b99e3036827d3ef8a

Request content

{
  "project": {
    "name": "Web app",
    "tag_list": "ruby, acme",
    "money_budget": 1200,
    "time_budget": 120
  }
}

Response

• 200 Ok
• 401 Unauthorized, invalid token
• 422 Unprocessable Entity, validation error

Successful response content

{
  "id": "57f9c9377c8402dd306d1c8b",
  "name": "Web app",
  "created_at": "2016-10-09T04:36:07.787Z",
  "updated_at": "2016-10-09T04:36:07.787Z",
  "tags": ["ruby", "acme"],
  "money_budget": 1200,
  "time_budget": 120
}

DELETE /api/projects/:id

Deletes one of current user's projects.

Auth header example

Authorization: d994a295cf68342b99e3036827d3ef8a

Response

• 204 No Content
• 401 Unauthorized, invalid token
• 404 Not Found

---

Leaderboards

GET /api/leaderboard/:period

Returns the users leaderboard for the selected period.

The period segment could be daily, weekly, monthly, and overall.

The list of leaderboard items is ordered by descending score and it's paginated. Each page contains 25 records, by default the first page is retuned, use the page parameter to get any other page in the range [1, total_pages].

Request parameters

• page a positive integer value to select a page in the range [1, total_pages]

Response

• 200 Ok

Response content

{
  "scores": [
    {
      "user": {
        "id": "586c2be37c8402b5d1db406c",
        "name": "Giovanni Cappellotto",
        "image": "http://tomato.es/images/users/586c2be37c8402b5d1db406c.png"
      },
      "score": 2
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 1
  }
}