├── README.md └── sections ├── clients.md ├── entries.md ├── projects.md ├── roles.md ├── tasks.md └── users.md /README.md: -------------------------------------------------------------------------------- 1 | Tick API 2 | ==================== 3 | 4 | This is version 2 of the Tick API. This API has been designed around RESTful concepts with JSON for serialization. 5 | 6 | URL 7 | --- 8 | All URLs start with `https://www.tickspot.com/9999/api/v2/`. **SSL only**. The path is prefixed with the subscription id and the API version. If we change the API in backward-incompatible ways, we'll bump the version marker and maintain stable support for the old URLs. 9 | 10 | 11 | Authentication 12 | -------------- 13 | 14 | Tick uses a simple token-based HTTP Authentication scheme. For clients to authenticate, the method "Token" and the token key should be included in the Authorization HTTP header. The key should be prefixed by the string literal "token=" with no whitespace. For example: 15 | 16 | ```shell 17 | Authorization: Token token=ApV99yzvwApV99yzvwApV99yzvwApV99yzvw 18 | ``` 19 | 20 | To retrieve your token check out the [roles](https://github.com/tick/tick-api/blob/master/sections/roles.md) section. 21 | 22 | User Agent 23 | ---------- 24 | A user agent that includes an email address is required to help us contact you should a need arise. 25 | 26 | ```shell 27 | User-Agent: MyCoolApp (me@example.com) 28 | ``` 29 | Body Format 30 | ---------- 31 | All data is serialized with JSON and UTF-8 encoded. This means that you have to send `Content-Type: application/json; charset=utf-8` when you're POSTing or PUTing data into Tick. All API URLs end in .json to indicate that they accept and return JSON. 32 | 33 | You'll receive a `415 Unsupported Media Type` response code if you attempt to use a different URL suffix or leave out the `Content-Type` header. 34 | 35 | Sample GET 36 | ------- 37 | To make a request for all the projects on your subscription, you'd append the projects index path to the base url to form something like https://www.tickspot.com/999999999/api/v2/projects.json. In cURL, that looks like: 38 | 39 | ```shell 40 | curl -H "Authorization: Token token=ApV99yzvwApV99yzvwApV99yzvwApV99yzvw" \ 41 | -H 'User-Agent: MyCoolApp (me@example.com)' \ 42 | https://www.tickspot.com/999999999/api/v2/projects.json 43 | ``` 44 | Sample POST 45 | ------------ 46 | To create something, it's the same deal except you also have to include the `Content-Type` header and the JSON data: 47 | 48 | ```shell 49 | curl -H "Authorization: Token token=ApV99yzvwApV99yzvwApV99yzvwApV99yzvw" \ 50 | -H 'Content-Type: application/json' \ 51 | -H 'User-Agent: MyCoolApp (me@example.com)' \ 52 | -d '{ "name": "My new project!", "client_id": "999" }' \ 53 | https://www.tickspot.com/999999999/api/v2/projects.json 54 | ``` 55 | 56 | Pagination 57 | ---------- 58 | 59 | Most collection APIs paginate their results. The first request returns up to 100 records. Check the next page for more results by adding the `page` parameter to your request. For example, `page=2`, then `page=3`, and so on until you get an empty response. 60 | 61 | Use HTTP caching 62 | ---------------- 63 | 64 | You must make use of the HTTP freshness headers to lessen the load on our servers (and increase the speed of your application!). Most requests we return will include an `ETag` or `Last-Modified` header. When you first request a resource, store this value, and then submit them back to us on subsequent requests as `If-None-Match` and `If-Modified-Since`. If the resource hasn't changed, you'll see a `304 Not Modified` response, which saves you the time and bandwidth of sending something you already have. 65 | 66 | 67 | Handling errors 68 | --------------- 69 | 70 | If Tick is having trouble, you might see a 5xx error. `500` means that the app is entirely down, but you might also see `502 Bad Gateway`, `503 Service Unavailable`, or `504 Gateway Timeout`. It's your responsibility in all of these cases to retry your request later. 71 | 72 | 73 | Thanks! 74 | ---------------------- 75 | 76 | Thank you for checking out Tick's API and please don't hesitate to reach out and let us know how you are using the API to help people track their time and hit their budgets. Feel free to use GitHub issues to post any issues or feature requests. 77 | 78 | Please tell us how we can make the API better. If you have a specific feature request or if you found a bug, please use GitHub issues. Fork these docs and send a pull request with improvements. 79 | 80 | To talk with us and other developers about the API, [post a question on StackOverflow](http://stackoverflow.com/questions/ask) tagged `tick` or [check out our support section](http://www.tickspot.com/help). 81 | -------------------------------------------------------------------------------- /sections/clients.md: -------------------------------------------------------------------------------- 1 | Clients 2 | ======== 3 | 4 | Get clients 5 | ------------ 6 | 7 | * `GET /clients.json` will return all the clients that have opened projects. 8 | * `GET /clients/all.json` will return all the clients. 9 | ```json 10 | [ 11 | { 12 | "id":12, 13 | "name":"The Republic", 14 | "archive":false, 15 | "url":"https://www.tickspot.com/api/v2/1/clients/12.json", 16 | "updated_at":"2014-09-09T13:36:20.000-04:00" 17 | }, 18 | { 19 | "id":3, 20 | "name":"The Empire", 21 | "archive":false, 22 | "url":"https://www.tickspot.com/api/v2/1/clients/3.json", 23 | "updated_at":"2014-09-09T13:36:19.000-04:00" 24 | } 25 | ] 26 | 27 | 28 | ``` 29 | 30 | Get client 31 | ---------- 32 | * `GET /clients/12.json` will return the specified client along with a summary of project information. 33 | 34 | ```json 35 | { 36 | "id":12, 37 | "name":"The Republic", 38 | "archive":false, 39 | "url":"https://www.tickspot.com/api/v2/1/clients/12.json", 40 | "updated_at":"2014-09-09T13:36:20.000-04:00", 41 | "projects":{ 42 | "count":1, 43 | "url":"https://www.tickspot.com/api/v2/123/clients/12/projects.json", 44 | "updated_at":"2014-09-09T13:36:20.000-04:00" 45 | } 46 | ``` 47 | 48 | Restricted Methods 49 | ---- 50 | The following methods **(create, update, and destroy)** are limited strictly to administrators on the subscription. If a non-administrator calls these methods a `403 Forbidden` will be returned. 51 | 52 | Create client 53 | ------------- 54 | * `POST /clients.json` will create a new client with the included parameters. 55 | 56 | ```json 57 | { 58 | "name":"The Hutts", 59 | "archive":false 60 | } 61 | ``` 62 | 63 | This will return `201 Created`, with the location of the new client in the `Location` header along with the current JSON representation of the client if the creation was a success. 64 | 65 | Update client 66 | ------------- 67 | * `PUT /clients/12.json` will update an existing client with the included parameters. 68 | 69 | ```json 70 | { 71 | "name":"The New Republic", 72 | "archive":false 73 | } 74 | ``` 75 | 76 | This will return `200 OK` along with the current JSON representation of the updated client if the creation was a success. 77 | 78 | Delete client 79 | ------------- 80 | 81 | * `DELETE /clients/12.json` will delete the client 82 | * Only clients **without any projects** can be deleted 83 | * If successful `204 No Content` will be returned. 84 | * If the client still has associated projects `406 Not Acceptable` will be returned. 85 | -------------------------------------------------------------------------------- /sections/entries.md: -------------------------------------------------------------------------------- 1 | Entries 2 | ======== 3 | 4 | Get entries 5 | ------------ 6 | 7 | * `GET /entries.json` will return all time entries that meet the provided parameters 8 | * `GET /users/4/entries.json` 9 | * `GET /projects/16/entries.json` 10 | * `GET /tasks/24/entries.json` 11 | * Either a ```start_date``` and ```end_date``` have to be provided **or** an ```updated_at``` time 12 | * Depending on what parameters are provided: 13 | * Entries will be between the ```start_date``` and ```end_date``` or 14 | * Entries created or modified after the ```updated_at``` time 15 | * Each of the following **optional** parameters can be used to filter the response: 16 | * ```billable``` (true/false) 17 | * ```project_id``` 18 | * ```task_id``` 19 | * ```user_id``` 20 | * ```billed``` (true/false) 21 | * Example returns billable time entries between two dates 22 | ```shell 23 | start_date='2014-09-01'&end_date='2014-09-02'&billable=true" 24 | ``` 25 | * Example returns a user's entries that have been updated after a specific time 26 | ```shell 27 | updated_at='2014-09-18T15:03:20.000-04:00'&user_id=12" 28 | ``` 29 | 30 | ```json 31 | 32 | [ 33 | { 34 | "id":"234", 35 | "date":"2014-09-17", 36 | "hours":2.88, 37 | "notes":"Stocking up on Bacta.", 38 | "task_id":24, 39 | "user_id":4, 40 | "url":"https://www.tickspot.com/api/v2/123/entries/234.json", 41 | "created_at":"2014-09-18T15:03:19.000-04:00", 42 | "updated_at":"2014-09-18T15:03:19.000-04:00" 43 | }, 44 | 45 | { 46 | "id":"235", 47 | "date":"2014-09-17", 48 | "hours":12, 49 | "notes":"Making the Kessel run.", 50 | "task_id":24, 51 | "user_id":4, 52 | "url":"https://www.tickspot.com/api/v2/123/entries/235.json", 53 | "created_at":"2014-09-18T15:03:19.000-04:00", 54 | "updated_at":"2014-09-18T15:03:19.000-04:00" 55 | } 56 | 57 | ] 58 | ``` 59 | 60 | 61 | Get entry 62 | ----------- 63 | 64 | * `GET /entries/235.json` will return the specified entry 65 | 66 | ```json 67 | { 68 | "id":"235", 69 | "date":"2014-09-17", 70 | "hours":12, 71 | "notes":"Making the Kessel run.", 72 | "task_id":24, 73 | "user_id":4, 74 | "url":"https://www.tickspot.com/api/v2/123/entries/235.json", 75 | "created_at":"2014-09-18T15:03:19.000-04:00", 76 | "updated_at":"2014-09-18T15:03:19.000-04:00", 77 | "task": 78 | { 79 | "id":"24", 80 | "name":"Install exhaust port", 81 | "budget":14.0, 82 | "position":1, 83 | "project_id":16, 84 | "date_closed":null, 85 | "billable":true, 86 | "url":"https://www.tickspot.com/api/v2/123/tasks/24.json", 87 | "created_at":"2014-09-18T15:03:18.000-04:00", 88 | "updated_at":"2014-09-18T15:03:18.000-04:00" 89 | }, 90 | } 91 | ``` 92 | 93 | Create entry 94 | -------------- 95 | 96 | * `POST /entries.json` will create a new entry from the parameters passed 97 | * The ```user_id``` will be ignored if the user is not an administrator 98 | 99 | ```json 100 | { 101 | "date":"2014-09-18", 102 | "hours":1.5, 103 | "notes":"Chasing Ewoks", 104 | "task_id":24, 105 | "user_id":4 106 | } 107 | ``` 108 | 109 | This will return `201 Created`, with the location of the new entry in the `Location` header along with the current JSON representation of the entry if the creation was a success. 110 | 111 | 112 | Update entry 113 | --------------- 114 | 115 | * `PUT /entries/235.json` will update the entry from the parameters passed 116 | 117 | ```json 118 | { 119 | "hours":12.5, 120 | "billed":true 121 | } 122 | ``` 123 | 124 | This will return `200 OK` if the update was a success along with the current JSON representation of the entry. 125 | 126 | Delete entry 127 | ------------- 128 | 129 | * `DELETE /entries/235.json` will delete the entry 130 | * If successful `204 No Content` will be returned 131 | -------------------------------------------------------------------------------- /sections/projects.md: -------------------------------------------------------------------------------- 1 | Projects 2 | ======== 3 | 4 | Get projects 5 | ------------ 6 | 7 | * `GET /projects.json` will return opened projects. 8 | * `GET /projects/closed.json` will return closed projects. 9 | 10 | * The first request returns up to 100 records and you can check the next page for more results by adding the `page` parameter to your request. For example, `page=2`, then `page=3`, and so on until you get an empty response. 11 | 12 | ```json 13 | [ 14 | { 15 | "id":16, 16 | "name":"Build Death Star", 17 | "budget":150.0, 18 | "date_closed":null, 19 | "notifications":false, 20 | "billable":true, 21 | "recurring":false, 22 | "client_id":12, 23 | "owner_id":3, 24 | "url":"https://www.tickspot.com/api/v2/123/projects/16.json", 25 | "created_at":"2014-09-09T13:36:20.000-04:00", 26 | "updated_at":"2014-09-09T13:36:20.000-04:00" 27 | }, 28 | { 29 | "id":4, 30 | "name":"Clean Up Alderaan", 31 | "budget":50.0, 32 | "date_closed":null, 33 | "notifications":false, 34 | "billable":true, 35 | "recurring":false, 36 | "client_id":3, 37 | "owner_id":3, 38 | "url":"https://www.tickspot.com/api/v2/123/projects/4.json", 39 | "created_at":"2014-09-09T13:36:19.000-04:00", 40 | "updated_at":"2014-09-09T13:36:19.000-04:00" 41 | } 42 | ] 43 | ``` 44 | 45 | Get project 46 | ----------- 47 | 48 | * `GET /projects/16.json` will return the specified project 49 | * Additionally the total hours that have been entered as well as a summary of task information is included. 50 | 51 | ```json 52 | { 53 | "id":16, 54 | "name":"Build Death Star", 55 | "budget":150.0, 56 | "date_closed":null, 57 | "notifications":false, 58 | "billable":true, 59 | "recurring":false, 60 | "client_id":12, 61 | "owner_id":3, 62 | "url":"https://www.tickspot.com/api/v2/123/projects/16.json", 63 | "created_at":"2014-09-09T13:36:20.000-04:00", 64 | "updated_at":"2014-09-09T13:36:20.000-04:00", 65 | "total_hours":22.0, 66 | "tasks": 67 | { 68 | "count":1, 69 | "url":"https://www.tickspot.com/api/v2/123/projects/16/tasks.json", 70 | "updated_at":null 71 | }, 72 | "client": 73 | { 74 | "id":12, 75 | "name":"Empire", 76 | "archive":false, 77 | "url":"https://www.tickspot.com/api/v2/123/clients/12.json", 78 | "updated_at":"2014-09-15T10:32:46.000-04:00" 79 | } 80 | } 81 | ``` 82 | 83 | Restricted Methods 84 | ---- 85 | The following methods **(create, update, and destroy)** are limited strictly to administrators on the subscription. If a non-administrator calls these methods a `403 Forbidden` will be returned. 86 | 87 | Create project 88 | -------------- 89 | 90 | * `POST /projects.json` will create a new project from the parameters passed. 91 | * No tasks will be created 92 | * Time entries will not be allowed until at least one task is created. 93 | 94 | ```json 95 | { 96 | "project": 97 | { 98 | "name":"Prepare Star Destroyer", 99 | "budget":50.0, 100 | "notifications":false, 101 | "billable":true, 102 | "recurring":false, 103 | "client_id":12, 104 | "owner_id":3 105 | } 106 | } 107 | ``` 108 | 109 | This will return `201 Created`, with the location of the new project in the `Location` header along with the current JSON representation of the project if the creation was a success. 110 | 111 | 112 | Update project 113 | --------------- 114 | 115 | * `PUT /projects/16.json` will update the project from the parameters passed. 116 | 117 | ```json 118 | { 119 | "project": 120 | { 121 | "budget":300, 122 | "billable":true 123 | } 124 | } 125 | ``` 126 | 127 | This will return `200 OK` if the update was a success along with the current JSON representation of the project. 128 | 129 | Delete project 130 | ------------- 131 | 132 | * `DELETE /projects/16.json` will delete the project 133 | * **WARNING:** The project **and all time entries** will be immediately deleted 134 | * If successful `204 No Content` will be returned. 135 | -------------------------------------------------------------------------------- /sections/roles.md: -------------------------------------------------------------------------------- 1 | Roles 2 | ======== 3 | Access to the Tick API requires the use of an API Token. Users can be granted access to multiple subscriptions and these are called **roles**. 4 | Unlike other areas of the API, a username and password must be provided using basic authentication. 5 | 6 | ```shell 7 | curl -u "email_address:password" \ 8 | -H 'User-Agent: MyCoolApp (me@example.com)' \ 9 | https://www.tickspot.com/api/v2/roles.json 10 | ``` 11 | 12 | API Token 13 | ------------ 14 | 15 | * Each role that a user is granted will automatically be assigned a token. 16 | * `GET /roles.json` will return all roles for the authenticated user. 17 | 18 | ```json 19 | [ 20 | { 21 | "subscription_id":15, 22 | "company":"Empire", 23 | "api_token":"f67158e7bf3d7a0fcaf9d258ace8b468" 24 | }, 25 | { 26 | "subscription_id":16, 27 | "company":"Republic", 28 | "api_token":"f67158e7bf3d7a0fcaf9d258ace8b468" 29 | } 30 | ] 31 | ``` -------------------------------------------------------------------------------- /sections/tasks.md: -------------------------------------------------------------------------------- 1 | Tasks 2 | ======== 3 | 4 | Get tasks 5 | ------------ 6 | 7 | * `GET /projects/16/tasks.json` will return all opened tasks for the project. 8 | * `GET /tasks.json` will return all opened tasks across all projects. 9 | 10 | ```json 11 | [ 12 | { 13 | "id":"25", 14 | "name":"Install exhaust port", 15 | "budget":14.0, 16 | "position":1, 17 | "project_id":16, 18 | "date_closed":null, 19 | "billable":true, 20 | "url":"https://www.tickspot.com/api/v2/123/tasks/28.json", 21 | "created_at":"2014-09-18T15:03:18.000-04:00", 22 | "updated_at":"2014-09-18T15:03:18.000-04:00" 23 | }, 24 | { 25 | "id":"26", 26 | "name":"Shield exhaust port", 27 | "budget":1.0, 28 | "position":2, 29 | "project_id":16, 30 | "date_closed":null, 31 | "billable":true, 32 | "url":"https://www.tickspot.com/api/v2/123/tasks/28.json", 33 | "created_at":"2014-09-18T15:03:18.000-04:00", 34 | "updated_at":"2014-09-18T15:03:18.000-04:00" 35 | } 36 | ] 37 | ``` 38 | 39 | Get closed tasks 40 | ------------ 41 | 42 | * `GET /projects/16/tasks/closed.json` will return all closed tasks for the project. 43 | * `GET /tasks/closed.json` will return all closed tasks across all projects. 44 | 45 | ```json 46 | [ 47 | { 48 | "id":"25", 49 | "name":"Install exhaust port", 50 | "budget":14.0, 51 | "position":1, 52 | "project_id":16, 53 | "date_closed":"2014-09-18", 54 | "billable":true, 55 | "url":"https://www.tickspot.com/api/v2/123/tasks/28.json", 56 | "created_at":"2014-09-18T15:03:18.000-04:00", 57 | "updated_at":"2014-09-18T15:03:18.000-04:00" 58 | }, 59 | { 60 | "id":"26", 61 | "name":"Shield exhaust port", 62 | "budget":1.0, 63 | "position":2, 64 | "project_id":16, 65 | "date_closed":"2014-09-18", 66 | "billable":true, 67 | "url":"https://www.tickspot.com/api/v2/123/tasks/28.json", 68 | "created_at":"2014-09-18T15:03:18.000-04:00", 69 | "updated_at":"2014-09-18T15:03:18.000-04:00" 70 | } 71 | ] 72 | ``` 73 | 74 | Get task 75 | ----------- 76 | 77 | * `GET /tasks/25.json` will return the specified task 78 | * Additionally the total hours that have been entered as well as a summary of entry information is included. 79 | 80 | ```json 81 | { 82 | "id":"25", 83 | "name":"Install exhaust port", 84 | "budget":14.0, 85 | "position":1, 86 | "project_id":16, 87 | "date_closed":null, 88 | "billable":true, 89 | "url":"https://www.tickspot.com/api/v2/123/tasks/28.json", 90 | "created_at":"2014-09-18T15:03:18.000-04:00", 91 | "updated_at":"2014-09-18T15:03:18.000-04:00", 92 | "total_hours":12.388, 93 | "entries": 94 | { 95 | "count":5, 96 | "url":"https://www.tickspot.com/api/v2/123/tasks/16/entries.json", 97 | "updated_at":"2014-09-18T15:03:21.000-04:00" 98 | }, 99 | "project": 100 | { 101 | "id":16, 102 | "name":"Build Death Star", 103 | "budget":150.0, 104 | "date_closed":null, 105 | "notifications":false, 106 | "billable":true, 107 | "recurring":false, 108 | "client_id":12, 109 | "owner_id":3, 110 | "url":"https://www.tickspot.com/api/v2/123/projects/16.json", 111 | "created_at":"2014-09-09T13:36:20.000-04:00", 112 | "updated_at":"2014-09-09T13:36:20.000-04:00" 113 | } 114 | } 115 | ``` 116 | 117 | Restricted Methods 118 | ---- 119 | The following methods **(create, update, and destroy)** are limited strictly to administrators on the subscription. If a non-administrator calls these methods a `403 Forbidden` will be returned. 120 | 121 | Create task 122 | -------------- 123 | 124 | * `POST /tasks.json` will create a new task from the parameters passed. 125 | 126 | ```json 127 | { 128 | "name":"Seriously shield exhaust port", 129 | "budget":1.0, 130 | "project_id":16, 131 | "billable":true, 132 | } 133 | ``` 134 | 135 | This will return `201 Created`, with the location of the new task in the `Location` header along with the current JSON representation of the task, if the creation was a success. 136 | 137 | 138 | Update task 139 | --------------- 140 | 141 | * `PUT /tasks/25.json` will update the task from the parameters passed. 142 | 143 | ```json 144 | { 145 | "budget":2, 146 | "billable":false 147 | } 148 | ``` 149 | 150 | This will return `200 OK` if the update was a success along with the current JSON representation of the task. 151 | 152 | Delete task 153 | ------------- 154 | 155 | * `DELETE /tasks/25.json` will delete the task 156 | * Only tasks **without any entries** can be deleted 157 | * If successful `204 No Content` will be returned. 158 | * If the task still has associated entries `406 Not Acceptable` will be returned. 159 | -------------------------------------------------------------------------------- /sections/users.md: -------------------------------------------------------------------------------- 1 | Users 2 | ======== 3 | 4 | Get users 5 | ------------ 6 | 7 | * `GET /users.json` will return information about the users on the subscription 8 | * Non-administrators will only have visibility of themselves while administrators will see everyone 9 | 10 | ```json 11 | [ 12 | { 13 | "id":4, 14 | "first_name":"Anakin", 15 | "last_name":"Skywalker", 16 | "email":"user@tickspot.com", 17 | "timezone":"Hawaii", 18 | "updated_at":"2014-11-19T12:53:46.000-05:00" 19 | }, 20 | { 21 | "id":1, 22 | "first_name":"Luke", 23 | "last_name":"Skywalker", 24 | "email":"owner@tickspot.com", 25 | "timezone":"Hawaii", 26 | "updated_at":"2015-01-30T15:13:44.000-05:00" 27 | } 28 | ] 29 | ``` 30 | 31 | Get deleted users 32 | ------------ 33 | 34 | * `GET /users/deleted.json` will return users who have been deleted from the subscription and have time entries 35 | * Non-administrators will not have access 36 | 37 | ```json 38 | [ 39 | { 40 | "id":5, 41 | "first_name":"Darth", 42 | "last_name":"Vader", 43 | "email":"dv@tickspot.com", 44 | "timezone":"Death Star", 45 | "updated_at":"2014-11-19T12:53:46.000-05:00" 46 | } 47 | ] 48 | ``` 49 | 50 | Create user 51 | ------------ 52 | 53 | * `POST /users.json` will create a user on the subscription 54 | * Only administrators will be able to create users 55 | 56 | ```json 57 | { 58 | "user": 59 | { 60 | "first_name":"Anakin", 61 | "last_name":"Skywalker", 62 | "email":"admin@tickspot.com", 63 | "admin":"true", 64 | "billable_rate": "100.0" 65 | } 66 | } 67 | ``` 68 | --------------------------------------------------------------------------------