Skip to content

docs(API): improve GET /projects/:id/documents documentation #1178

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Stephen Lumenta (sbl) wants to merge 1 commit into from
+45 −12
Closed

docs(API): improve GET /projects/:id/documents documentation #1178

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 19 additions & 5 deletions doc/compiled.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5569,7 +5569,7 @@
"/projects/{project_id}/documents": {
"get": {
"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.\n\nUse 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.\n\nDocuments 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.\n\nPitfalls:\n- 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.\n- The `per_page` parameter defaults to 25 and is capped at 100. Requests exceeding this cap are clamped silently.\n- Rate limits apply; requests exceeding the account limit return 429. Retry after the interval indicated by the `X-Rate-Limit-Reset` response header.\n",
"operationId": "documents/list",
"tags": [
"Documents"
Expand All @@ -5588,7 +5588,7 @@
"$ref": "#/components/parameters/project_id"
},
{
"description": "Search query. Filters documents by name (case-insensitive substring match).",
"description": "Filter documents by name. Case-insensitive substring match against the document name field.\n",
"name": "q",
"in": "query",
"example": "invoice",
Expand All @@ -5599,7 +5599,7 @@
],
"responses": {
"200": {
"description": "OK",
"description": "OK — returns an array of document objects. Pagination metadata is in the `Link` response header.",
"content": {
"application/json": {
"schema": {
Expand Down Expand Up @@ -5630,7 +5630,21 @@
"updated_at": "2015-01-28T09:52:53Z"
}
}
}
},
"example": [
{
"id": "abcd1234cdef1234abcd1234cdef1234",
"name": "email.html",
"created_at": "2024-03-15T10:22:00Z",
"updated_at": "2024-03-16T08:45:00Z"
},
{
"id": "beef5678cafe5678beef5678cafe5678",
"name": "marketing-landing.html",
"created_at": "2024-02-01T14:00:00Z",
"updated_at": "2024-02-10T09:10:00Z"
}
]
}
},
"headers": {
Expand Down Expand Up @@ -5671,7 +5685,7 @@
"x-code-samples": [
{
"lang": "Curl",
"source": "curl \"https://api.phrase.com/v2/documents?project_id=asdf\" \\\n -u USERNAME_OR_ACCESS_TOKEN"
"source": "curl \"https://api.phrase.com/v2/projects/:project_id/documents?q=invoice&page=1&per_page=25\" \\\n -u USERNAME_OR_ACCESS_TOKEN"
},
{
"lang": "CLI v2",
Expand Down
33 changes: 26 additions & 7 deletions paths/documents/index.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,16 @@
---
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.

@jablan jablan Jun 12, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


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.

@jablan jablan Jun 12, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


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.

@jablan jablan Jun 12, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please do not expose identifier names from internal applications.

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

@theSoenke Sönke Behrendt (theSoenke) Jun 12, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • the policy should not be part of the api docs
  • per page and rate limit details do not need to repeated per endpoint

@jablan jablan Jun 12, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rate limiting applies universally and is explained on a dedicated place. I see no benefit of repeating this information everywhere (similar to pagination).

operationId: documents/list
tags:
- Documents
Expand All @@ -9,22 +19,31 @@ parameters:
- "$ref": "../../parameters.yaml#/page"
- "$ref": "../../parameters.yaml#/per_page"
- "$ref": "../../parameters.yaml#/project_id"
- description: |-
Search query. Filters documents by name (case-insensitive substring match).
- description: |
Filter documents by name. Case-insensitive substring match against the document name field.
name: q
in: query
example: invoice
schema:
type: string
responses:
'200':
description: OK
description: OK — returns an array of document objects. Pagination metadata is in the `Link` response header.
content:
application/json:
schema:
type: array
items:
"$ref": "../../schemas/document.yaml#/document"
example:
- id: abcd1234cdef1234abcd1234cdef1234
name: email.html
created_at: '2024-03-15T10:22:00Z'
updated_at: '2024-03-16T08:45:00Z'
- id: beef5678cafe5678beef5678cafe5678
name: marketing-landing.html
created_at: '2024-02-01T14:00:00Z'
updated_at: '2024-02-10T09:10:00Z'
headers:
X-Rate-Limit-Limit:
"$ref": "../../headers.yaml#/X-Rate-Limit-Limit"
Expand All @@ -38,19 +57,19 @@ responses:
"$ref": "../../headers.yaml#/Pagination"
'400':
"$ref": "../../responses.yaml#/400"
'404':
"$ref": "../../responses.yaml#/404"
'401':
"$ref": "../../responses.yaml#/401"
'403':
"$ref": "../../responses.yaml#/403"
description: Forbidden. Returned when the access token lacks the `read` scope or when the requesting user is not allowed to list documents in this project.
'404':
"$ref": "../../responses.yaml#/404"
'429':
"$ref": "../../responses.yaml#/429"
x-code-samples:
- lang: Curl
source: |-
curl "https://api.phrase.com/v2/documents?project_id=asdf" \
curl "https://api.phrase.com/v2/projects/:project_id/documents?q=invoice&page=1&per_page=25" \
-u USERNAME_OR_ACCESS_TOKEN
- lang: CLI v2
source: |-
Expand Down
Loading