Skip to content

PLATB-38: Cursor Pagination on Photos Endpoint #34

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

Open
VikiAnn wants to merge 8 commits into
base: main
Choose a base branch
from
Open

PLATB-38: Cursor Pagination on Photos Endpoint #34

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
1535a69
Add cursor pagination info to /photos endpoint documentation
VikiAnn Jan 14, 2026
78bf93c
Add missing documentation for project_id query param and photo schema…
VikiAnn Jan 14, 2026
140223f
Fix wording issues & return type for photo coordinates
VikiAnn Jan 14, 2026
5c666e2
Clarify page param description
VikiAnn Jan 15, 2026
4f138ff
Nest Coordinate ref inside allOf property so that description renders
VikiAnn Jan 15, 2026
7523024
Make relationship between cursor headers and params more explicit
VikiAnn Jan 15, 2026
86bd72a
Remove pagination-specific language from bad request description
VikiAnn Jan 21, 2026
6f0df01
Add cursor pagination to /projects/:project_id/photos endpoint docs
VikiAnn Feb 24, 2026
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
115 changes: 100 additions & 15 deletions openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -827,22 +827,36 @@ paths:
format: id
- name: page
in: query
description: "Page number for offset-based pagination. Cannot be used with cursor pagination (after/before params)"
schema:
type: integer
format: int32
- name: per_page
in: query
description: "Number of results per page. Default 50, maximum 100"
schema:
type: integer
format: int32
default: 50
maximum: 100
- name: after
in: query
description: "Cursor for forward pagination. Comes from X-Next-Cursor header value. Returns results after this cursor position. Cannot be used with 'before' or 'page'"
schema:
type: string
- name: before
in: query
description: "Cursor for backward pagination. Comes from X-Prev-Cursor header value. Returns results before this cursor position. Cannot be used with 'after' or 'page'"
schema:
type: string
- name: start_date
in: query
description: "A unix timestamp to return photos modified on or after the provided value"
description: "A unix timestamp to return photos captured on or after the provided value"
schema:
type: string
- name: end_date
in: query
description: "A unix timestamp to return photos modified on or before the provided value"
description: "A unix timestamp to return photos captured on or before the provided value"
schema:
type: string
- name: user_ids
Expand All @@ -855,23 +869,42 @@ paths:
format: int64
- name: group_ids
in: query
description: "Filter results to include photos captured by one of these group IDs"
description: "Filter results to include photos captured by users in one of these group IDs"
schema:
type: array
items:
type: integer
format: int64
- name: tag_ids
in: query
description: "Filter results to include photos captured by one of these tag IDs"
description: "Filter results to include photos with one of these tag IDs"
schema:
type: array
items:
type: integer
format: int64
responses:
"200":
description: "List of projects sorted by most recent activity first"
description: "List of photos sorted by captured date descending"
headers:
X-Next-Cursor:
description: "Cursor that can be used as an 'after' param to fetch the next page of results. Empty if no more results"
schema:
type: string
X-Prev-Cursor:
description: "Cursor that can be used as a 'before' param to fetch the previous page of results. Empty if no previous results"
schema:
type: string
X-Has-Next:
description: "Indicates whether more results exist after the current page"
schema:
type: string
enum: ["true", "false"]
X-Has-Prev:
description: "Indicates whether results exist before the current page"
schema:
type: string
enum: ["true", "false"]
content:
application/json:
schema:
Expand Down Expand Up @@ -1941,24 +1974,46 @@ paths:
parameters:
- name: page
in: query
description: "Page number for offset-based pagination. Cannot be used with cursor pagination (after/before params)"
schema:
type: integer
format: int32
- name: per_page
in: query
description: "Number of results per page. Default 50, maximum 100"
schema:
type: integer
format: int32
default: 50
maximum: 100
- name: after
in: query
description: "Cursor for forward pagination. Comes from X-Next-Cursor header value. Returns results after this cursor position. Cannot be used with 'before' or 'page'"
schema:
type: string
- name: before
in: query
description: "Cursor for backward pagination. Comes from X-Prev-Cursor header value. Returns results before this cursor position. Cannot be used with 'after' or 'page'"
schema:
type: string
- name: start_date
in: query
description: "A unix timestamp to return photos modified on or after the provided value"
description: "A unix timestamp to return photos captured on or after the provided value"
Comment on lines -1954 to +2001
Copy link
Author

@VikiAnn VikiAnn Jan 16, 2026

Choose a reason for hiding this comment

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

Changes from here to L1980/L2002 are small corrections unrelated to the new cursor pagination behavior

schema:
type: string
- name: end_date
in: query
description: "A unix timestamp to return photos modified on or before the provided value"
description: "A unix timestamp to return photos captured on or before the provided value"
schema:
type: string
- name: project_ids
in: query
description: "Filter results to include photos from one of these project IDs"
schema:
type: array
items:
type: integer
format: int64
- name: user_ids
in: query
description: "Filter results to include photos captured by one of these user IDs"
Expand All @@ -1969,23 +2024,42 @@ paths:
format: int64
- name: group_ids
in: query
description: "Filter results to include photos captured by one of these group IDs"
description: "Filter results to include photos captured by users in one of these group IDs"
schema:
type: array
items:
type: integer
format: int64
- name: tag_ids
in: query
description: "Filter results to include photos captured by one of these tag IDs"
description: "Filter results to include photos with one of these tag IDs"
schema:
type: array
items:
type: integer
format: int64
responses:
"200":
description: "List of projects sorted by most recent activity first"
description: "List of photos sorted by captured date descending"
headers:
X-Next-Cursor:
description: "Cursor that can be used as an 'after' param to fetch the next page of results. Empty if no more results"
schema:
type: string
X-Prev-Cursor:
description: "Cursor that can be used as a 'before' param to fetch the previous page of results. Empty if no previous results"
schema:
type: string
X-Has-Next:
description: "Indicates whether more results exist after the current page"
schema:
type: string
enum: ["true", "false"]
X-Has-Prev:
description: "Indicates whether results exist before the current page"
schema:
type: string
enum: ["true", "false"]
content:
application/json:
schema:
Expand All @@ -1998,8 +2072,15 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
errors: ["Bad Request"]
examples:
both_cursors:
summary: Both cursors provided
value:
errors: ["Cannot use both 'after' and 'before' parameters"]
mixed_pagination:
summary: Mixed pagination types
value:
errors: ["Cannot use cursor pagination with offset pagination"]
"404":
description: "Not found"
content:
Expand Down Expand Up @@ -3434,11 +3515,15 @@ components:
"duplicate",
]
example: "processed"
status:
type: string
description: "The status of the Photo"
enum: ["active", "deleted"]
example: "active"
coordinates:
type: array
description: "The coordinates where the Photo was captured"
items:
$ref: "#/components/schemas/Coordinate"
allOf:
- $ref: "#/components/schemas/Coordinate"
Comment on lines +3518 to +3526
Copy link
Author

@VikiAnn VikiAnn Jan 16, 2026

Choose a reason for hiding this comment

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

Also just small corrections unrelated to the new cursor pagination behavior.

uris:
type: array
description: "A list of URIs for the different size variants of the photo."
Expand Down
Loading