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:

Request

POST /api/session

Request content

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

Response

Response content

{
  "token": "d994a295cf68342b99e3036827d3ef8a"
}

DELETE /api/session

Deletes all Tomatoes API active sessions for the current user.

Auth header example

Authorization: d994a295cf68342b99e3036827d3ef8a

Response


User

GET /api/user

Returns current user's data.

Auth header example

Authorization: d994a295cf68342b99e3036827d3ef8a

Response

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

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

Response

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

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

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

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


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

Response

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

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

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

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


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

Response

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
  }
}