Skip to content

Rallly is an open-source scheduling and collaboration tool designed to make organizing events and meetings easier.

🔥 Return every poll participant in one response instead of paginating (#3285)

Luke Vella607487ca5beb
diff --git a/apps/docs/api-reference/introduction.mdx b/apps/docs/api-reference/introduction.mdx
index a04143a5c..cdc766961 100644
--- a/apps/docs/api-reference/introduction.mdx
+++ b/apps/docs/api-reference/introduction.mdx
@@ -24,7 +24,7 @@ https://api.rallly.co/v1
## Conventions
- Requests and responses are JSON. Send `Content-Type: application/json` with a body.
-- List endpoints return the items in `data` and a `nextCursor` beside it. Pass `nextCursor` as the `cursor` query parameter for the next page; it is `null` on the last page.
+- List endpoints return the items in `data`. `GET /polls` is paginated: it returns a `nextCursor` beside `data`; pass it as the `cursor` query parameter for the next page, and it is `null` on the last page. `GET /polls/:pollId/participants` returns every participant in one response.
- Timestamps are ISO 8601 instants in UTC. A `date` poll's options carry a floating `YYYY-MM-DD` date with no timezone; a `time` poll's options carry a `startTime` instant and a `duration` in minutes.
- Request bodies are validated strictly. A field that is not in the schema is rejected rather than ignored, so a misspelt setting never silently falls back to its default.
diff --git a/apps/docs/api-reference/openapi.json b/apps/docs/api-reference/openapi.json
index 5aee425d8..356327494 100644
--- a/apps/docs/api-reference/openapi.json
+++ b/apps/docs/api-reference/openapi.json
@@ -2,7 +2,7 @@
"openapi": "3.1.0",
"info": {
"title": "Rallly API",
- "description": "## Versioning\n\n`v1` is stable. Additive changes (new endpoints, new optional fields) may land on this path at any time; breaking changes only arrive under a new version prefix.\n\n## Rate limits\n\nAll endpoints share two limits per space: **60 requests per minute** and **5000 requests per day**. Both are fixed windows that open with the first request and reset when they expire. Both limits are per space, not per API key, so creating additional keys does not increase throughput.\n\nEvery response from an authenticated request includes the standard `RateLimit-*` headers. Responses sent before the limiter runs (`401`, `403`, and the maintenance `503`) do not. `RateLimit-Policy` lists both limits; `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` describe whichever limit is closest to being exhausted. When either limit is exceeded the API responds with `429 Too Many Requests`, a `RATE_LIMIT_EXCEEDED` error body, and a `Retry-After` header indicating how many seconds to wait before retrying.\n\nIf the rate limit store cannot be reached the API fails closed and responds with `503 Service Unavailable`, a `SERVICE_UNAVAILABLE` error body, and a `Retry-After` header.\n\n## Dates and times\n\nEvery poll has a `kind`. A `date` poll offers calendar days: each option carries a `date` in `YYYY-MM-DD` format, which is a floating date with no time component and no timezone, so never convert it through a timezone. A `time` poll offers time slots: each option carries a `startTime` as an ISO 8601 instant in UTC and a `duration` in minutes; convert `startTime` into the poll's `timeZone` (or the viewer's) for display. Timestamps such as `createdAt` and `updatedAt` are always ISO 8601 instants in UTC.\n\n## Request bodies\n\nRequest bodies are validated strictly: a field that is not part of the documented schema is rejected with `VALIDATION_ERROR` rather than ignored, so a misspelt setting never silently falls back to its default.\n\n## Enums\n\nVote types are an open set. The built-in values are `yes`, `ifNeedBe` and `no`; new types may be added without a version change, so clients must tolerate values they do not recognise. `status` and `kind` are closed sets.\n\n## Lists\n\nEvery list endpoint returns the items in `data` and a `nextCursor` beside it. Pass `nextCursor` as the `cursor` query parameter to fetch the next page; it is `null` on the last page.\n\n## Errors\n\nEvery failure is `application/json` with the shape `{ \"error\": { \"code\", \"message\" } }`. `code` is stable and safe to branch on; `message` is human-readable and may change. `VALIDATION_ERROR` messages name each offending field.\n\n| Status | Code | When |\n| --- | --- | --- |\n| 400 | `VALIDATION_ERROR` | The body or query string did not match the schema, contained an unknown field, or the body was not valid JSON |\n| 400 | `INVALID_AUTHORIZATION_HEADER` | The `Authorization` header is not `Bearer <key>` |\n| 400 | `ORGANIZER_NOT_MEMBER` | The organizer email is not a member of the space |\n| 400 | `TOO_MANY_OPTIONS` | More than the maximum number of poll options |\n| 400 | `INAPPROPRIATE_CONTENT` | The title, description or location was flagged by content moderation |\n| 401 | `UNAUTHORIZED` | The API key is missing, invalid, expired or revoked, or its owner is banned |\n| 403 | `SPACE_NOT_PRO` | The space behind the key has no Pro subscription |\n| 404 | `NOT_FOUND` | No route matches the method and path |\n| 404 | `POLL_NOT_FOUND` | The poll does not exist or belongs to another space |\n| 429 | `RATE_LIMIT_EXCEEDED` | A rate limit window is exhausted |\n| 503 | `SERVICE_UNAVAILABLE` | Maintenance, or the rate limit store cannot be reached |\n| 500 | `INTERNAL_ERROR` | Unexpected failure; the request id is logged |",
+ "description": "## Versioning\n\n`v1` is stable. Additive changes (new endpoints, new optional fields) may land on this path at any time; breaking changes only arrive under a new version prefix.\n\n## Rate limits\n\nAll endpoints share two limits per space: **60 requests per minute** and **5000 requests per day**. Both are fixed windows that open with the first request and reset when they expire. Both limits are per space, not per API key, so creating additional keys does not increase throughput.\n\nEvery response from an authenticated request includes the standard `RateLimit-*` headers. Responses sent before the limiter runs (`401`, `403`, and the maintenance `503`) do not. `RateLimit-Policy` lists both limits; `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` describe whichever limit is closest to being exhausted. When either limit is exceeded the API responds with `429 Too Many Requests`, a `RATE_LIMIT_EXCEEDED` error body, and a `Retry-After` header indicating how many seconds to wait before retrying.\n\nIf the rate limit store cannot be reached the API fails closed and responds with `503 Service Unavailable`, a `SERVICE_UNAVAILABLE` error body, and a `Retry-After` header.\n\n## Dates and times\n\nEvery poll has a `kind`. A `date` poll offers calendar days: each option carries a `date` in `YYYY-MM-DD` format, which is a floating date with no time component and no timezone, so never convert it through a timezone. A `time` poll offers time slots: each option carries a `startTime` as an ISO 8601 instant in UTC and a `duration` in minutes; convert `startTime` into the poll's `timeZone` (or the viewer's) for display. Timestamps such as `createdAt` and `updatedAt` are always ISO 8601 instants in UTC.\n\n## Request bodies\n\nRequest bodies are validated strictly: a field that is not part of the documented schema is rejected with `VALIDATION_ERROR` rather than ignored, so a misspelt setting never silently falls back to its default.\n\n## Enums\n\nVote types are an open set. The built-in values are `yes`, `ifNeedBe` and `no`; new types may be added without a version change, so clients must tolerate values they do not recognise. `status` and `kind` are closed sets.\n\n## Lists\n\nList endpoints return the items in `data`. `GET /polls` is paginated: it returns a `nextCursor` beside `data`; pass it as the `cursor` query parameter to fetch the next page, and it is `null` on the last page. `GET /polls/:pollId/participants` returns every participant in one response.\n\n## Errors\n\nEvery failure is `application/json` with the shape `{ \"error\": { \"code\", \"message\" } }`. `code` is stable and safe to branch on; `message` is human-readable and may change. `VALIDATION_ERROR` messages name each offending field.\n\n| Status | Code | When |\n| --- | --- | --- |\n| 400 | `VALIDATION_ERROR` | The body or query string did not match the schema, contained an unknown field, or the body was not valid JSON |\n| 400 | `INVALID_AUTHORIZATION_HEADER` | The `Authorization` header is not `Bearer <key>` |\n| 400 | `ORGANIZER_NOT_MEMBER` | The organizer email is not a member of the space |\n| 400 | `TOO_MANY_OPTIONS` | More than the maximum number of poll options |\n| 400 | `INAPPROPRIATE_CONTENT` | The title, description or location was flagged by content moderation |\n| 401 | `UNAUTHORIZED` | The API key is missing, invalid, expired or revoked, or its owner is banned |\n| 403 | `SPACE_NOT_PRO` | The space behind the key has no Pro subscription |\n| 404 | `NOT_FOUND` | No route matches the method and path |\n| 404 | `POLL_NOT_FOUND` | The poll does not exist or belongs to another space |\n| 429 | `RATE_LIMIT_EXCEEDED` | A rate limit window is exhausted |\n| 503 | `SERVICE_UNAVAILABLE` | Maintenance, or the rate limit store cannot be reached |\n| 500 | `INTERNAL_ERROR` | Unexpected failure; the request id is logged |",
"version": "1.0.0"
},
"servers": [
@@ -879,23 +879,10 @@
"items": {
"$ref": "#/components/schemas/Participant"
}
- },
- "nextCursor": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "Cursor to fetch the next page. `null` when there are no more results.",
- "example": "cm5j2r8wb0003q9l4a1x6p0zt"
}
},
"required": [
- "data",
- "nextCursor"
+ "data"
]
},
"DeletePollResponse": {
@@ -1601,7 +1588,7 @@
"Polls"
],
"summary": "List poll participants",
- "description": "Lists the participants of a poll, oldest response first. The poll must belong to the space associated with the API key.\n\nResults are paginated with a cursor: pass the `nextCursor` value from the previous response to fetch the next page. Per-option answers are not included; use the results endpoint for aggregate availability.",
+ "description": "Lists every participant of a poll in one response, oldest response first. The poll must belong to the space associated with the API key.\n\nPer-option answers are not included; use the results endpoint for aggregate availability.",
"security": [
{
"bearerAuth": []
@@ -1618,16 +1605,6 @@
}
}
},
- "400": {
- "description": "Invalid query parameters",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrorResponse"
- }
- }
- }
- },
"401": {
"description": "The API key is missing, invalid, expired or revoked, or its owner is banned. Includes a `WWW-Authenticate` header.",
"headers": {
@@ -1704,27 +1681,6 @@
}
},
"parameters": [
- {
- "in": "query",
- "name": "cursor",
- "schema": {
- "example": "cm5j2r8wb0003q9l4a1x6p0zt",
- "type": "string"
- },
- "description": "Cursor for pagination. Pass the `nextCursor` value from the previous response to fetch the next page."
- },
- {
- "in": "query",
- "name": "limit",
- "schema": {
- "default": 50,
- "example": 50,
- "type": "integer",
- "minimum": 1,
- "maximum": 100
- },
- "description": "Number of participants to return per page (1-100)."
- },
{
"schema": {
"type": "string"
diff --git a/apps/web/src/app/api/v1/[...route]/route.test.ts b/apps/web/src/app/api/v1/[...route]/route.test.ts
index b98b414ac..e67228788 100644
--- a/apps/web/src/app/api/v1/[...route]/route.test.ts
+++ b/apps/web/src/app/api/v1/[...route]/route.test.ts
@@ -2683,7 +2683,6 @@ describe("API v1 - /polls", () => {
mockGetPollParticipants.mockResolvedValue({
pollId: "test-poll-id",
participants: [],
- nextCursor: null,
});
mockListPolls.mockResolvedValue({ polls: [], nextCursor: null });
@@ -2723,7 +2722,6 @@ describe("API v1 - /polls", () => {
mockGetPollParticipants.mockResolvedValue({
pollId: "test-poll-id",
participants,
- nextCursor: null,
});
const res = await app.request("/v1/polls/test-poll-id/participants", {
@@ -2745,21 +2743,18 @@ describe("API v1 - /polls", () => {
createdAt: "2025-01-10T10:00:00.000Z",
});
expect(json.data[1].email).toBeNull();
- expect(json.nextCursor).toBeNull();
+ expect(json).not.toHaveProperty("nextCursor");
expect(mockGetPollParticipants).toHaveBeenCalledWith({
pollId: "test-poll-id",
spaceId: "test-space-id",
- cursor: undefined,
- limit: 50,
});
});
- it("should pass the cursor and limit through and return the next cursor", async () => {
+ it("should return every participant and ignore pagination query parameters", async () => {
mockGetPollParticipants.mockResolvedValue({
pollId: "test-poll-id",
- participants: [participants[1]],
- nextCursor: "participant-2",
+ participants,
});
const res = await app.request(
@@ -2776,38 +2771,20 @@ describe("API v1 - /polls", () => {
const json = await res.json();
expectMatchesContract(getPollParticipantsSuccessResponseSchema, json);
expect(json.data.map((p: { id: string }) => p.id)).toEqual([
+ "participant-1",
"participant-2",
]);
- expect(json.nextCursor).toBe("participant-2");
expect(mockGetPollParticipants).toHaveBeenCalledWith({
pollId: "test-poll-id",
spaceId: "test-space-id",
- cursor: "participant-1",
- limit: 1,
});
});
- it("should return 400 when limit is out of range", async () => {
- const res = await app.request(
- "/v1/polls/test-poll-id/participants?limit=500",
- {
- method: "GET",
- headers: {
- Authorization: `Bearer ${testApiKey}`,
- },
- },
- );
-
- await expectErrorEnvelope(res, { status: 400, code: "VALIDATION_ERROR" });
- expect(mockGetPollParticipants).not.toHaveBeenCalled();
- });
-
it("should return empty array when no participants", async () => {
mockGetPollParticipants.mockResolvedValue({
pollId: "test-poll-id",
participants: [],
- nextCursor: null,
});
const res = await app.request("/v1/polls/test-poll-id/participants", {
@@ -2821,7 +2798,6 @@ describe("API v1 - /polls", () => {
const json = await res.json();
expect(json.data).toEqual([]);
- expect(json.nextCursor).toBeNull();
});
it("should return 404 when poll not found", async () => {
diff --git a/apps/web/src/app/api/v1/[...route]/route.ts b/apps/web/src/app/api/v1/[...route]/route.ts
index 969e69dd7..36c536bbe 100644
--- a/apps/web/src/app/api/v1/[...route]/route.ts
+++ b/apps/web/src/app/api/v1/[...route]/route.ts
@@ -45,7 +45,6 @@ import {
errorResponseSchema,
getPollParticipantsSuccessResponseSchema,
getPollResultsSuccessResponseSchema,
- listParticipantsQuerySchema,
listPollsQuerySchema,
listPollsSuccessResponseSchema,
pollResponseSchema,
@@ -290,7 +289,7 @@ async function buildOpenApiSpec() {
"",
"## Lists",
"",
- "Every list endpoint returns the items in `data` and a `nextCursor` beside it. Pass `nextCursor` as the `cursor` query parameter to fetch the next page; it is `null` on the last page.",
+ "List endpoints return the items in `data`. `GET /polls` is paginated: it returns a `nextCursor` beside `data`; pass it as the `cursor` query parameter to fetch the next page, and it is `null` on the last page. `GET /polls/:pollId/participants` returns every participant in one response.",
"",
"## Errors",
"",
@@ -846,9 +845,9 @@ app.get(
tags: ["Polls"],
summary: "List poll participants",
description: [
- "Lists the participants of a poll, oldest response first. The poll must belong to the space associated with the API key.",
+ "Lists every participant of a poll in one response, oldest response first. The poll must belong to the space associated with the API key.",
"",
- "Results are paginated with a cursor: pass the `nextCursor` value from the previous response to fetch the next page. Per-option answers are not included; use the results endpoint for aggregate availability.",
+ "Per-option answers are not included; use the results endpoint for aggregate availability.",
].join("\n"),
security: [{ bearerAuth: [] }],
responses: {
@@ -860,14 +859,6 @@ app.get(
},
},
},
- 400: {
- description: "Invalid query parameters",
- content: {
- "application/json": {
- schema: resolver(errorResponseSchema),
- },
- },
- },
401: unauthorizedResponse,
403: spaceNotProResponse,
429: rateLimitExceededResponse,
@@ -882,13 +873,11 @@ app.get(
},
},
}),
- validator("query", listParticipantsQuerySchema, validationHook),
async (c) => {
const { pollId } = c.req.param();
- const { cursor, limit } = c.req.valid("query");
const { spaceId } = c.get("apiAuth");
- const data = await getPollParticipants({ pollId, spaceId, cursor, limit });
+ const data = await getPollParticipants({ pollId, spaceId });
if (!data) {
return c.json(
@@ -908,7 +897,6 @@ app.get(
email: participant.email,
createdAt: participant.createdAt.toISOString(),
})),
- nextCursor: data.nextCursor,
}),
);
},
diff --git a/apps/web/src/app/api/v1/schemas.ts b/apps/web/src/app/api/v1/schemas.ts
index cab7934ad..d9faaa04d 100644
--- a/apps/web/src/app/api/v1/schemas.ts
+++ b/apps/web/src/app/api/v1/schemas.ts
@@ -585,25 +585,8 @@ export const participantSchema = z
})
.meta({ id: "Participant" });
-export const listParticipantsQuerySchema = z.object({
- cursor: z.string().optional().meta({
- description:
- "Cursor for pagination. Pass the `nextCursor` value from the previous response to fetch the next page.",
- example: "cm5j2r8wb0003q9l4a1x6p0zt",
- }),
- limit: z.coerce.number().int().min(1).max(100).default(50).meta({
- description: "Number of participants to return per page (1-100).",
- example: 50,
- }),
-});
-
export const getPollParticipantsSuccessResponseSchema = z
.object({
data: z.array(participantSchema),
- nextCursor: z.string().nullable().meta({
- description:
- "Cursor to fetch the next page. `null` when there are no more results.",
- example: "cm5j2r8wb0003q9l4a1x6p0zt",
- }),
})
.meta({ id: "GetPollParticipantsResponse" });
diff --git a/apps/web/src/features/poll/data.ts b/apps/web/src/features/poll/data.ts
index 6641bae9f..bcfecbe47 100644
--- a/apps/web/src/features/poll/data.ts
+++ b/apps/web/src/features/poll/data.ts
@@ -135,19 +135,14 @@ export async function getPollResults({
}
/**
- * Participants in response order (oldest first) with their recorded votes.
- * Pass `limit` to page with a cursor; omit it to return every participant.
+ * Every participant in response order (oldest first).
*/
export async function getPollParticipants({
pollId,
spaceId,
- cursor,
- limit,
}: {
pollId: string;
spaceId: AuthorizedSpaceId;
- cursor?: string;
- limit?: number;
}) {
const poll = await prisma.poll.findFirst({
where: {
@@ -165,8 +160,6 @@ export async function getPollParticipants({
createdAt: true,
},
orderBy: [{ createdAt: "asc" }, { id: "asc" }],
- ...(limit !== undefined && { take: limit + 1 }),
- ...(cursor && { cursor: { id: cursor }, skip: 1 }),
},
},
});
@@ -175,13 +168,9 @@ export async function getPollParticipants({
return null;
}
- const hasMore = limit !== undefined && poll.participants.length > limit;
- const page = hasMore ? poll.participants.slice(0, limit) : poll.participants;
-
return {
pollId: poll.id,
- participants: page,
- nextCursor: hasMore ? (page[page.length - 1]?.id ?? null) : null,
+ participants: poll.participants,
};
}