update api v2 docs #14
Conversation
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. WalkthroughDocumentation in Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
📜 Recent review detailsConfiguration used: Repository: TaskRatchet/coderabbit/.coderabbit.yaml Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
✨ 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. Comment |
User-Visible ImprovementsThis PR contains 4 user-visible improvements:
Last updated: 2025-09-07T14:34:25.507Z |
There was a problem hiding this comment.
Pull Request Overview
This PR updates the API v2 documentation by adding query parameters documentation for the GET /api2/me/tasks endpoint and fixing a formatting issue in the POST endpoint description.
- Added comprehensive query parameters table for task filtering and pagination
- Fixed trailing backslash in POST endpoint description
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
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)
151-151: Fix typo: “authenticted” → “authenticated”.User-facing docs; please correct.
-You'll need to be authenticted in order to reset your token. If you don't already have a token, contact support for help. +You'll need to be authenticated in order to reset your token. If you don't already have a token, contact support for help.
122-131: Makerecurrence.daysconditionally required and integer-typed-| recurrence.days | number | true | Number of days between recurrences | +| recurrence.days | integer | conditional | Number of days between recurrences (required if `recurrence` is provided) | Note: `recurrence.days` must be an integer ≥ 1 when `recurrence` is present.
♻️ Duplicate comments (1)
src/api-v2.md (1)
80-86: Clarify pagination indexing, page size, status enum, and timestamp semantics.
- Past nit: default page 0 vs 1. If 0-based is intentional, say so; otherwise switch to 1-based default 1. Also document page_size/limit and max. Define status enum/case and timestamp units/boundaries.
-| page | number | false | Page number (default: 0) | -| status | string | false | Filter by task status (pending, complete, expired) | -| due_before | number | false | Unix timestamp; only return tasks due before this time | -| due_after | number | false | Unix timestamp; only return tasks due after this time | +| page | number | false | 0-based page number (default: 0). Consider 1-based for UX consistency. | +| page_size | number | false | Number of tasks per page (default: 50, max: 200). | +| status | string | false | One of: pending | complete | expired (case-insensitive). | +| due_before | number | false | Unix timestamp in seconds (UTC); returns tasks due at or before this time. | +| due_after | number | false | Unix timestamp in seconds (UTC); returns tasks due at or after this time. |Note: If both due_after and due_before are provided, clarify whether due_after <= due_before is required and the error returned otherwise.
🧹 Nitpick comments (3)
src/api-v2.md (3)
4-7: Tighten the warning block; add versioning/deprecation guidance.Consider adding a brief note on versioning/deprecation policy (e.g., how breaking changes are announced) to set expectations.
::: warning -This version of the API is in active development. The -API and its associated documentation are likely to be incomplete and/or incorrect, -and may change without notice. +This version of the API is in active development. The API and its documentation may change without notice. +Breaking changes: Announced via release notes and the changelog; no stability guarantees until v2 is marked stable. :::
87-97: Document pagination metadata; array-only responses leave clients guessing.If the endpoint is paginated, expose navigation info (Link header or envelope with total/page/page_size). At minimum, document headers if already implemented.
Response format: | Response Field | Type | Description | ... | status | string | The task's status (pending, complete, expired) | + +Pagination: + +- If using HTTP Link headers, document rel="next" and rel="prev" examples. +- If using a response envelope, prefer: + +```json +{ + "data": [ /* tasks */ ], + "pagination": { "page": 0, "page_size": 50, "total": 1234, "total_pages": 25 } +} +```
124-129: Tighten numeric types and constraints.due and cents should be integers if they represent seconds and whole cents. Document minimums (e.g., cents ≥ 0) and any future-time requirement for due.
-| 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, UTC) of the task's due date | +| cents | integer| true | The task's stakes in cents (≥ 0) |
|
@coderabbitai full review |
✅ Actions performedFull review triggered. |
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/api-v2.md (1)
151-151: Fix typo: “authenticted” → “authenticated”.
User-facing typo in security-sensitive section.Apply:
-You'll need to be authenticted in order to reset your token. If you don't already have a token, contact support for help. +You'll need to be authenticated in order to reset your token. If you don't already have a token, contact support for help.
♻️ Duplicate comments (1)
src/api-v2.md (1)
78-86: Tighten param specs; clarify paging default and time units.
- Use integer types for page and timestamps; specify epoch units/timezone.
- Document whether due_before/after are inclusive/exclusive.
- For status, explicitly list allowed values and note case sensitivity.
- Re: default page=0 vs 1, align with product convention or clarify 0-based indexing.
Proposed edits:
-| page | number | false | Page number (default: 0) | -| status | string | false | Filter by task status (pending, complete, expired) | -| due_before | number | false | Unix timestamp; only return tasks due before this time | -| due_after | number | false | Unix timestamp; only return tasks due after this time | +| page | integer | false | Page number (0-based; default: 0) | +| status | string | false | One of: pending, complete, expired (case-sensitive) | +| due_before | integer | false | Unix timestamp (seconds, UTC); tasks due before this time | +| due_after | integer | false | Unix timestamp (seconds, UTC); tasks due after this time |If you prefer 1-based pages, change the description to “1-based; default: 1” and update examples accordingly.
🧹 Nitpick comments (2)
src/api-v2.md (2)
87-88: Document pagination mechanics in the response.
State page size, max page size, and how to fetch the next page (e.g., page param, Link headers, or cursors).
122-131: Clarify conditional requirement and integer types for POST body.
- Make recurrence.days “Required if recurrence is provided.”
- Use integer and specify epoch units/timezone.
- Consider minimum constraints (e.g., recurrence.days >= 1).
Proposed edits:
-| Field | Type | Required | Description | +| Field | Type | Required | Description | ... -| due | number | true | Unix timestamp of the task's due date | +| due | integer | true | Unix timestamp (seconds, UTC) of the task's due date | ... -| 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 | +| recurrence.days | integer | conditional | Number of days between recurrences; required if recurrence is provided (min: 1) |
📜 Review details
Configuration used: Repository: TaskRatchet/coderabbit/.coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
src/api-v2.md(3 hunks)
🔇 Additional comments (1)
src/api-v2.md (1)
4-4: Concise warning text LGTM.
Wording is clearer while preserving the caution.
narthur
temporarily deployed
to
api-docs - docs.tr.com PR #14
Render
Destroyed
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
Summary by CodeRabbit