document token routes #12
Conversation
There was a problem hiding this comment.
Pull Request Overview
This PR adds documentation for token management routes in the API v2 documentation. The change provides users with information about how to retrieve and reset their API v2 tokens.
- Added documentation for two new token-related endpoints
- Fixed table formatting alignment for consistency
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
WalkthroughRefactored API v2 docs in Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant U as User
participant C as Client (UI)
participant API as API v2 (/api2)
rect rgba(200,230,255,0.25)
note over U,C: Retrieve token
U->>C: Click "Show Token"
C->>API: GET /api2/me/token
API-->>C: 200 OK { token }
C-->>U: Display token
end
rect rgba(255,230,200,0.25)
note over U,C: Reset token
U->>C: Click "Reset Token"
C->>API: POST /api2/me/token
API-->>C: 200 OK { token: new_value }
C-->>U: Confirm and show new token
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
User-Visible ImprovementsThis PR contains 3 user-visible improvements:
Last updated: 2025-08-27T15:50:46.848Z |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
src/api-v2.md (1)
38-39: Add minimal, concrete sections for the new token routes (payload, codes, security).Right now the schema table lists the routes but there are no route sections like the others. Please document:
- Exact request/response schema and status codes.
- Rotation semantics: when the old token becomes invalid.
- Headers: recommend
Cache-Control: no-storeand warn against logging/printing the token.- Example curl.
Proposed stubs to insert below “POST /me/tasks”:
### `POST /me/token` Resets your API v2 token. The previous token becomes invalid immediately (confirm). - Request body: empty. - Responses: - 201 Created — returns the new token. - 401/403 — auth required/forbidden. Example response: ```json { "token": "trv2_XXXXXXXXXXXXXXXXXXXXXXXX" }
GET /me/tokenReturns your current API v2 token (confirm that it’s retrievable after creation).
- Responses:
- 200 OK — returns the token.
- 401/403 — auth required/forbidden.
Security:
- Do not log this value. Responses SHOULD include
Cache-Control: no-store.Example:
curl "https://api.taskratchet.com/api2/me/token" \ -H "Authorization: ApiKey-v2 YOUR_API_V2_TOKEN"Would you like me to open a follow-up PR adding these sections once you confirm the exact payloads/status codes? </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used**: CodeRabbit UI **Review profile**: CHILL **Plan**: Pro **💡 Knowledge Base configuration:** - MCP integration is disabled by default for public repositories - Jira integration is disabled by default for public repositories - Linear integration is disabled by default for public repositories You can enable these sources in your CodeRabbit configuration. <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between fe45bb0fba7eb8519158658270eb6e7646931ccf and d5b5f56a9001c20e5822785a05bcf146e58c1bff. </details> <details> <summary>📒 Files selected for processing (1)</summary> * `src/api-v2.md` (1 hunks) </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>🪛 LanguageTool</summary> <details> <summary>src/api-v2.md</summary> [grammar] ~32-~32: There might be a mistake here. Context: ...point | Description | | --------------- | --------------------... (QB_NEW_EN) --- [grammar] ~33-~33: There might be a mistake here. Context: ...------------ | ----------------------- | | `GET me` | Get your profile dat... (QB_NEW_EN) --- [grammar] ~34-~34: There might be a mistake here. Context: ...T me` | Get your profile data | | `DEL me` | Delete your account ... (QB_NEW_EN) --- [grammar] ~35-~35: There might be a mistake here. Context: ...L me` | Delete your account | | `GET me/tasks` | Get all your tasks ... (QB_NEW_EN) --- [grammar] ~36-~36: There might be a mistake here. Context: ...T me/tasks` | Get all your tasks | | `POST me/tasks` | Create a new task ... (QB_NEW_EN) --- [grammar] ~37-~37: There might be a mistake here. Context: ...ST me/tasks` | Create a new task | | `POST me/token` | Reset your API v2 to... (QB_NEW_EN) --- [grammar] ~38-~38: There might be a mistake here. Context: ...ST me/token` | Reset your API v2 token | | `GET me/token` | Get your API v2 toke... (QB_NEW_EN) </details> </details> </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
src/api-v2.md (2)
113-121: Fix requiredness of recurrence fields and expand request example.
recurrenceis optional, sorecurrence.dayscannot be unconditionally required. Make it conditional and add an example request with Content-Type.Apply this diff to the field table:
-| recurrence | object | false | The task's recurrence settings | -| recurrence.days | number | true | Number of days between recurrences | +| recurrence | object | false | The task's recurrence settings (omit for one-off tasks) | +| recurrence.days | number | conditional | Number of days between recurrences (required when `recurrence` is provided) |Add a request example:
curl -X POST "https://api.taskratchet.com/api2/me/tasks" \ -H "Authorization: ApiKey-v2 YOUR_API_V2_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "task": "Take out the trash", "due": 1614556800, "cents": 100, "recurrence": { "days": 7 } }'
74-87: Clarify pagination contract on GET/api2/me/tasksThe current docs state that this endpoint “is paginated,” but don’t specify how clients should page through results. Please extend the section at
src/api-v2.md(lines 74–87) with the following details:• Whether paging is 0- or 1-based
• Default page size and maximum page size
• Supported query parameters (e.g.,page,limit,sort)
• Default sort order (for example,dueascending)
• Any pagination headers or link objects returned (e.g.,Link,X-Total-Count, or JSON:APIlinks)Providing these guarantees prevents client-side guesswork and integration bugs.
♻️ Duplicate comments (1)
src/api-v2.md (1)
32-39: Use canonical HTTP verb and add docs for token endpoints.
- Replace non-standard
DELwithDELETE.- The two token routes are listed but lack sections describing request/response, security implications, and examples.
Apply this diff for the table:
-| `DEL /api2/me` | Delete your account | +| `DELETE /api2/me` | Delete your account |Add sections for the token routes (example content to insert later in the file):
### `GET /api2/me/token` Returns your API v2 token. - Auth: required - Response: `{ "token": "..." }` - Errors: `401 Unauthorized` ### `POST /api2/me/token` Rotates (invalidates and replaces) your API v2 token. - Auth: required - Response: `{ "token": "..." }` - Notes: Old token becomes invalid immediately. - Errors: `401 Unauthorized`
🧹 Nitpick comments (1)
src/api-v2.md (1)
41-41: Document error responses for unauthorized calls.Add a brief Errors block (e.g.,
401 Unauthorized) and a minimal error JSON example forGET /api2/me.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
src/api-v2.md(3 hunks)
🧰 Additional context used
🪛 LanguageTool
src/api-v2.md
[grammar] ~32-~32: There might be a mistake here.
Context: ...point | Description | | --------------- | --------------------...
(QB_NEW_EN)
[grammar] ~33-~33: There might be a mistake here.
Context: ...------------ | ----------------------- | | GET /api2/me | Get your profi...
(QB_NEW_EN)
[grammar] ~34-~34: There might be a mistake here.
Context: ...2/me | Get your profile data | |DEL /api2/me` | Delete your ac...
(QB_NEW_EN)
[grammar] ~35-~35: There might be a mistake here.
Context: ...2/me | Delete your account | |GET /api2/me/tasks` | Get all your t...
(QB_NEW_EN)
[grammar] ~36-~36: There might be a mistake here.
Context: ...2/me/tasks | Get all your tasks | |POST /api2/me/tasks` | Create a new t...
(QB_NEW_EN)
[grammar] ~37-~37: There might be a mistake here.
Context: ...i2/me/tasks| Create a new task | |POST /api2/me/token` | Reset your API...
(QB_NEW_EN)
[grammar] ~38-~38: There might be a mistake here.
Context: ...i2/me/token| Reset your API v2 token | |GET /api2/me/token` | Get your API v...
(QB_NEW_EN)
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
src/api-v2.md (2)
74-87: Paginated route needs parameters and navigation details.You mention pagination but don’t define the contract (query params, indexing, defaults, navigation).
-Returns an array of tasks. This route is paginated. +Returns an array of tasks. This route is paginated. + +Query parameters +- `page` (integer, default `0`): 0-based page index. +- `limit` (integer, default `50`, max `200`): page size. + +Response +- `200 OK` with an array of tasks (below). +- Pagination navigation via `Link` header when applicable: + `Link: <https://api.taskratchet.com/api2/me/tasks?page=1&limit=50>; rel="next"` +- Errors: `401 Unauthorized`, `429 Too Many Requests`.Optional: include a short example showing the
Linkheader in the example response block.
113-120: Tighten field types and requirements for POST /api2/me/tasks.Use integers for monetary amounts and epoch seconds; clarify conditional requiredness.
-| Field | Type | Required | Description | -| --------------- | ------ | -------- | ------------------------------------- | -| task | string | true | The task description | -| due | number | true | Unix timestamp of the task's due date | -| cents | number | true | The task's stakes in cents | -| recurrence | object | false | The task's recurrence settings | -| recurrence.days | number | true | Number of days between recurrences | +| Field | Type | Required | Description | +| --------------- | ------- | -------- | --------------------------------------------------- | +| task | string | true | The task description | +| due | integer | true | Unix timestamp (seconds) of the task's due date | +| cents | integer | true | The task's stakes in cents (min 1) | +| recurrence | object | false | The task's recurrence settings | +| recurrence.days | integer | cond. | Number of days between recurrences (required if `recurrence` is provided) |Also add request/response semantics and headers:
-On success, the response will be the created task object. +Request headers +- `Content-Type: application/json` + +On success, the response will be the created task object. + +Response +- `201 Created` with the created task in the body. May include `Location: /api2/me/tasks/<id>`. +- Errors: `400 Bad Request` (validation), `401 Unauthorized`, `429 Too Many Requests`.Optional request example:
{ "task": "Write API docs", "due": 1735689600, "cents": 500, "recurrence": { "days": 7 } }
♻️ Duplicate comments (1)
src/api-v2.md (1)
70-70: DELETE semantics missing (status, idempotency, errors).For destructive ops, specify exact behavior.
-### `DELETE /api2/me` - -Deletes the user's account. This action is irreversible. +### `DELETE /api2/me` + +Deletes the user's account. This action is irreversible. + +Response +- `204 No Content` on success. This operation is idempotent; repeating it returns `204` if the account is already deleted. +- Errors: `401 Unauthorized`, `403 Forbidden` (if extra confirmation required), `429 Too Many Requests`.
🧹 Nitpick comments (2)
src/api-v2.md (2)
41-41: Document success and error semantics for GET /api2/me.Add status codes and common errors so clients can handle failures consistently.
-### `GET /api2/me` +### `GET /api2/me` + +Response +- `200 OK` with the user object (below). +- Errors: `401 Unauthorized` (missing/invalid token), `429 Too Many Requests`.
32-39: Minor: keep Base URL and paths consistent.You show a Base URL and also repeat
/api2in each endpoint. Either approach works; consider removing/api2from the table entries to reduce duplication since you already declare the base. Up to you.-| `GET /api2/me` | Get your profile data | +| `GET /me` | Get your profile data |(Apply similarly for the other rows if you choose this style.)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
src/api-v2.md(3 hunks)
🧰 Additional context used
🪛 LanguageTool
src/api-v2.md
[grammar] ~32-~32: There might be a mistake here.
Context: ... | Description | | --------------------- | --------------...
(QB_NEW_EN)
[grammar] ~33-~33: There might be a mistake here.
Context: ...------------ | ----------------------- | | GET /api2/me | Get your profi...
(QB_NEW_EN)
[grammar] ~34-~34: There might be a mistake here.
Context: ...2/me | Get your profile data | |DELETE /api2/me` | Delete your ac...
(QB_NEW_EN)
[grammar] ~35-~35: There might be a mistake here.
Context: ...api2/me | Delete your account | |GET /api2/me/tasks` | Get all your t...
(QB_NEW_EN)
[grammar] ~36-~36: There might be a mistake here.
Context: ...2/me/tasks | Get all your tasks | |POST /api2/me/tasks` | Create a new t...
(QB_NEW_EN)
[grammar] ~37-~37: There might be a mistake here.
Context: ...i2/me/tasks| Create a new task | |POST /api2/me/token` | Reset your API...
(QB_NEW_EN)
[grammar] ~38-~38: There might be a mistake here.
Context: ...i2/me/token| Reset your API v2 token | |GET /api2/me/token` | Get your API v...
(QB_NEW_EN)
narthur
temporarily deployed
to
api-docs - docs.tr.com PR #12
Render
Destroyed
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
src/api-v2.md (1)
136-145: Complete token route docs; fix typo; include auth, responses, and security notes.These endpoints need auth header, examples, response shapes, and error semantics. Typo: “authenticted”.
-### `POST /api2/me/token` - -Reset your account's API v2 token. This will invalidate the old token and generate a new one. - -You'll need to be authenticted in order to reset your token. If you don't already have a token, contact support for help. +### `POST /api2/me/token` + +Rotate your account's API v2 token. The old token is invalidated immediately. + +Auth: +`Authorization: ApiKey-v2 <token>` + +Response: +- `200 OK` +```json +{ "token": "tr_v2_YYYYYYYYYYYYYYYY" } +``` + +Errors: +- `401 Unauthorized` (missing/invalid auth) +- `429 Too Many Requests` + +Security: +- Treat the returned token as secret. Do not expose it client-side or commit it. + +Example: +```bash +curl -X POST "https://api.taskratchet.com/api2/me/token" \ + -H "Authorization: ApiKey-v2 YOUR_API_V2_TOKEN" -i +``` ### `GET /api2/me/token` -Returns the current API v2 token for the authenticated user. +Returns the current API v2 token for the authenticated user. + +Auth: +`Authorization: ApiKey-v2 <token>` + +Response: +- `200 OK` +```json +{ "token": "tr_v2_XXXXXXXXXXXXXXXX" } +``` + +Errors: +- `401 Unauthorized` +- `429 Too Many Requests`
🧹 Nitpick comments (2)
src/api-v2.md (2)
32-39: Good normalization; prefer “Rotate” over “Reset” for token wording.Endpoints table looks solid. Minor wording tweak improves clarity and aligns with standard terminology.
-| `POST /api2/me/token` | Reset your API v2 token | +| `POST /api2/me/token` | Rotate your API v2 token |
109-134: Tighten types and add request example; confirm success status.Use integer types for money and timestamps; include a concrete request payload and status code.
Creates a new task. The request body should be a JSON object with the following fields:\ | Field | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------------- | | task | string | true | The task description | -| due | number | true | Unix timestamp of the task's due date | -| cents | number | true | The task's stakes in cents | +| due | integer| true | Unix timestamp (seconds) | +| cents | integer| true | The task's stakes in cents | | recurrence | object | false | The task's recurrence settings | -| recurrence.days | number | true | Number of days between recurrences | +| recurrence.days | integer| true | Number of days between recurrences | -On success, the response will be the created task object. +On success, the response will be the created task object. +Status: `201 Created` (confirm), with `Location` header pointing to the task URL (confirm). + +Example request: +```bash +curl -X POST "https://api.taskratchet.com/api2/me/tasks" \ + -H "Authorization: ApiKey-v2 YOUR_API_V2_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ "task":"Take out the trash", "due":1614556800, "cents":100, "recurrence":{"days":7} }' +```Please confirm
201 Createdvs200 OKand whetherLocationis returned.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
src/api-v2.md(4 hunks)
🧰 Additional context used
🪛 LanguageTool
src/api-v2.md
[grammar] ~32-~32: There might be a mistake here.
Context: ... | Description | | --------------------- | --------------...
(QB_NEW_EN)
[grammar] ~33-~33: There might be a mistake here.
Context: ...------------ | ----------------------- | | GET /api2/me | Get your profi...
(QB_NEW_EN)
[grammar] ~34-~34: There might be a mistake here.
Context: ...2/me | Get your profile data | |DELETE /api2/me` | Delete your ac...
(QB_NEW_EN)
[grammar] ~35-~35: There might be a mistake here.
Context: ...api2/me | Delete your account | |GET /api2/me/tasks` | Get all your t...
(QB_NEW_EN)
[grammar] ~36-~36: There might be a mistake here.
Context: ...2/me/tasks | Get all your tasks | |POST /api2/me/tasks` | Create a new t...
(QB_NEW_EN)
[grammar] ~37-~37: There might be a mistake here.
Context: ...i2/me/tasks| Create a new task | |POST /api2/me/token` | Reset your API...
(QB_NEW_EN)
[grammar] ~38-~38: There might be a mistake here.
Context: ...i2/me/token| Reset your API v2 token | |GET /api2/me/token` | Get your API v...
(QB_NEW_EN)
[grammar] ~140-~140: Ensure spelling is correct
Context: ... generate a new one. You'll need to be authenticted in order to reset your token. If you do...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~140-~140: Consider a more concise word here.
Context: ...ew one. You'll need to be authenticted in order to reset your token. If you don't already ...
(IN_ORDER_TO_PREMIUM)
🔇 Additional comments (2)
src/api-v2.md (2)
74-87: Clarify and document the pagination contract forGET /api2/me/tasksI wasn’t able to find any implementation details in the code (e.g., route handler, pagination helper, or Link-header construction), so we need to confirm how pagination actually works and then update the docs accordingly.
Please verify and then document:
- Query parameters (names, types, defaults, max/min values):
•page(integer, zero-based index, default: 0)
•per_page(integer, items per page, default: X, max: Y)- Pagination mechanism:
• Are we using RFC 5988 Link headers withrel="next"/"prev"?
• Or a JSON response envelope with metadata (e.g.{ data: [...], page, per_page, total })?- Example response showing the chosen pagination model and headers.
— File:
src/api-v2.md@ lines 74–87
70-72: Verify DELETE /api2/me response semanticsI wasn’t able to locate the implementation of the
DELETE /api2/mehandler in this repo, so please confirm the intended behavior in production before updating the docs:
- Does a successful deletion return 204 No Content, and is it safe to repeat the request (i.e. idempotent)?
- Does it return 401 Unauthorized when the authentication header is missing or invalid?
- Does it return 429 Too Many Requests when the rate limit is exceeded?
Once confirmed, please apply this diff to
src/api-v2.mdaround lines 70–72:### `DELETE /api2/me` -Deletes the user's account. This action is irreversible. +Deletes the user's account. This action is irreversible. + +Responses: +- `204 No Content` on success (idempotent: repeat calls also return 204). +- `401 Unauthorized` if auth is missing or invalid. +- `429 Too Many Requests` if rate limit exceeded. + +Example: +```bash +curl -X DELETE "https://api.taskratchet.com/api2/me" \ + -H "Authorization: ApiKey-v2 YOUR_API_V2_TOKEN" -i +```
Summary by CodeRabbit
Documentation
New Features