docs(API): improve GET /projects/:id/documents documentation#1178
Open
Stephen Lumenta (sbl) wants to merge 1 commit into
Open
docs(API): improve GET /projects/:id/documents documentation#1178Stephen Lumenta (sbl) wants to merge 1 commit into
Stephen Lumenta (sbl) wants to merge 1 commit into
Conversation
Adds conceptual description (why/model including Link header pagination following RFC 5988), documents 401/403 responses with causes, improves curl example to use path param format, adds response example with realistic document values, and fixes q parameter description. Part of DEVEX-119. 🤖 Generated with Claude Code (claude-sonnet-4-6)
Stephen Lumenta (sbl)
added
the
developer-hub-api-quality
| Pitfalls: | ||
| - Results are scoped to documents the authenticated user can read via `DocumentPolicy#list_documents?`. Users without project read access see an empty list, not a 403. | ||
| - The `per_page` parameter defaults to 25 and is capped at 100. Requests exceeding this cap are clamped silently. | ||
| - Rate limits apply; requests exceeding the account limit return 429. Retry after the interval indicated by the `X-Rate-Limit-Reset` response header. |
Collaborator
There was a problem hiding this comment.
- the policy should not be part of the api docs
- per page and rate limit details do not need to repeated per endpoint
jablan
reviewed
Jun 12, 2026
| summary: List documents | ||
| description: List all documents the current user has access to. | ||
| description: | | ||
| Returns a paginated list of documents in the specified project that the current user has access to. |
Collaborator
There was a problem hiding this comment.
I don't think it's helpful to say the list is paginated here. Most of our responses are paginated and pagination is explained in the separate section.
jablan
reviewed
Jun 12, 2026
|
|
||
| Use this endpoint to retrieve the document inventory for a project — for example, to display a list of source files in a dashboard, or to programmatically determine which documents are available before fetching segments. | ||
|
|
||
| Documents are ordered by creation date (newest first). Pagination is communicated via the `Link` response header following RFC 5988 (Web Linking); use the `next` and `prev` relations to traverse pages. The `q` parameter performs a case-insensitive substring match on document names. |
Collaborator
There was a problem hiding this comment.
as mentioned, I think pagination information is superfluous here. Other information (such as sorting, on endpoints which do not offer sorting-specific parameters which are documented separately) is welcome.
jablan
reviewed
Jun 12, 2026
| Documents are ordered by creation date (newest first). Pagination is communicated via the `Link` response header following RFC 5988 (Web Linking); use the `next` and `prev` relations to traverse pages. The `q` parameter performs a case-insensitive substring match on document names. | ||
|
|
||
| Pitfalls: | ||
| - Results are scoped to documents the authenticated user can read via `DocumentPolicy#list_documents?`. Users without project read access see an empty list, not a 403. |
Collaborator
There was a problem hiding this comment.
Please do not expose identifier names from internal applications.
jablan
reviewed
Jun 12, 2026
| Pitfalls: | ||
| - Results are scoped to documents the authenticated user can read via `DocumentPolicy#list_documents?`. Users without project read access see an empty list, not a 403. | ||
| - The `per_page` parameter defaults to 25 and is capped at 100. Requests exceeding this cap are clamped silently. | ||
| - Rate limits apply; requests exceeding the account limit return 429. Retry after the interval indicated by the `X-Rate-Limit-Reset` response header. |
Collaborator
There was a problem hiding this comment.
Rate limiting applies universally and is explained on a dedicated place. I see no benefit of repeating this information everywhere (similar to pagination).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Improves the documentation for
GET /projects/:project_id/documents(list documents).Changes
?project_id=asdfquery param; now correctly uses:project_idpath param formatqparameter descriptionAll changes are spec-layer only (paths/documents/index.yaml + compiled bundle). No Ruby source edits.
Part of DEVEX-119.
Drafted with AI assistance and grounded in the strings-app source. Please review for technical accuracy before merging; nothing is merged automatically.
🤖 Generated with Claude Code