Skip to content

Commit c89e179

Browse files
leggetterleggetter
committed
fix: add pagination support to event listings in OpenAPI documentation
1 parent d72b81b commit c89e179

File tree

1 file changed

+145
-38
lines changed

1 file changed

+145
-38
lines changed

‎docs/apis/openapi.yaml‎

Lines changed: 145 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,27 @@ components:
7979
description: '"*" or an array of enabled topics.'
8080
example: "*"
8181

82+
PaginatedResponse:
83+
type: object
84+
required: [count, data, next, prev]
85+
properties:
86+
count:
87+
type: integer
88+
description: Total number of items across all pages
89+
example: 42
90+
data:
91+
type: array
92+
items: {} # Will be overridden by specific endpoints
93+
description: Array of items for current page
94+
next:
95+
type: string
96+
description: Cursor for next page (empty string if no next page)
97+
example: ""
98+
prev:
99+
type: string
100+
description: Cursor for previous page (empty string if no previous page)
101+
example: ""
102+
82103
# Destination Type Specific Config/Credentials Schemas
83104
WebhookConfig:
84105
type: object
@@ -1930,33 +1951,76 @@ paths:
19301951
type: string
19311952
enum: [success, failed]
19321953
description: Filter events by delivery status.
1933-
# Add cursor parameters (e.g., 'after', 'limit') when defined
1954+
- name: next
1955+
in: query
1956+
required: false
1957+
schema:
1958+
type: string
1959+
description: Cursor for next page of results
1960+
- name: prev
1961+
in: query
1962+
required: false
1963+
schema:
1964+
type: string
1965+
description: Cursor for previous page of results
1966+
- name: limit
1967+
in: query
1968+
required: false
1969+
schema:
1970+
type: integer
1971+
default: 100
1972+
minimum: 1
1973+
maximum: 1000
1974+
description: Number of items per page (default 100, max 1000)
1975+
- name: start
1976+
in: query
1977+
required: false
1978+
schema:
1979+
type: string
1980+
format: date-time
1981+
description: Start time filter (RFC3339 format)
1982+
- name: end
1983+
in: query
1984+
required: false
1985+
schema:
1986+
type: string
1987+
format: date-time
1988+
description: End time filter (RFC3339 format)
19341989
responses:
19351990
"200":
1936-
description: A list of events.
1991+
description: A paginated list of events.
19371992
content:
19381993
application/json:
19391994
schema:
1940-
type: array
1941-
items:
1942-
$ref: "#/components/schemas/Event"
1995+
allOf:
1996+
- $ref: "#/components/schemas/PaginatedResponse"
1997+
- type: object
1998+
properties:
1999+
data:
2000+
type: array
2001+
items:
2002+
$ref: "#/components/schemas/Event"
19432003
examples:
19442004
EventsListExample:
19452005
value:
1946-
- id: "evt_123"
1947-
destination_id: "des_456"
1948-
topic: "user.created"
1949-
time: "2024-01-01T00:00:00Z"
1950-
successful_at: "2024-01-01T00:00:05Z"
1951-
metadata: { "source": "crm" }
1952-
data: { "user_id": "userid", "status": "active" }
1953-
- id: "evt_789"
1954-
destination_id: "des_456"
1955-
topic: "order.shipped"
1956-
time: "2024-01-02T10:00:00Z"
1957-
successful_at: null
1958-
metadata: { "source": "oms" }
1959-
data: { "order_id": "orderid", "tracking": "1Z..." }
2006+
count: 2
2007+
data:
2008+
- id: "evt_123"
2009+
destination_id: "des_456"
2010+
topic: "user.created"
2011+
time: "2024-01-01T00:00:00Z"
2012+
successful_at: "2024-01-01T00:00:05Z"
2013+
metadata: { "source": "crm" }
2014+
data: { "user_id": "userid", "status": "active" }
2015+
- id: "evt_789"
2016+
destination_id: "des_456"
2017+
topic: "order.shipped"
2018+
time: "2024-01-02T10:00:00Z"
2019+
successful_at: null
2020+
metadata: { "source": "oms" }
2021+
data: { "order_id": "orderid", "tracking": "1Z..." }
2022+
next: ""
2023+
prev: ""
19602024
"404":
19612025
description: Tenant not found.
19622026
# Add other error responses
@@ -2071,33 +2135,76 @@ paths:
20712135
type: string
20722136
enum: [success, failed]
20732137
description: Filter events by delivery status.
2074-
# Add cursor parameters
2138+
- name: next
2139+
in: query
2140+
required: false
2141+
schema:
2142+
type: string
2143+
description: Cursor for next page of results
2144+
- name: prev
2145+
in: query
2146+
required: false
2147+
schema:
2148+
type: string
2149+
description: Cursor for previous page of results
2150+
- name: limit
2151+
in: query
2152+
required: false
2153+
schema:
2154+
type: integer
2155+
default: 100
2156+
minimum: 1
2157+
maximum: 1000
2158+
description: Number of items per page (default 100, max 1000)
2159+
- name: start
2160+
in: query
2161+
required: false
2162+
schema:
2163+
type: string
2164+
format: date-time
2165+
description: Start time filter (RFC3339 format)
2166+
- name: end
2167+
in: query
2168+
required: false
2169+
schema:
2170+
type: string
2171+
format: date-time
2172+
description: End time filter (RFC3339 format)
20752173
responses:
20762174
"200":
2077-
description: A list of events for the destination.
2175+
description: A paginated list of events for the destination.
20782176
content:
20792177
application/json:
20802178
schema:
2081-
type: array
2082-
items:
2083-
$ref: "#/components/schemas/Event"
2179+
allOf:
2180+
- $ref: "#/components/schemas/PaginatedResponse"
2181+
- type: object
2182+
properties:
2183+
data:
2184+
type: array
2185+
items:
2186+
$ref: "#/components/schemas/Event"
20842187
examples:
20852188
EventsListExample: # Same as /{tenant_id}/events example
20862189
value:
2087-
- id: "evt_123"
2088-
destination_id: "des_456"
2089-
topic: "user.created"
2090-
time: "2024-01-01T00:00:00Z"
2091-
successful_at: "2024-01-01T00:00:05Z"
2092-
metadata: { "source": "crm" }
2093-
data: { "user_id": "userid", "status": "active" }
2094-
- id: "evt_789"
2095-
destination_id: "des_456"
2096-
topic: "order.shipped"
2097-
time: "2024-01-02T10:00:00Z"
2098-
successful_at: null
2099-
metadata: { "source": "oms" }
2100-
data: { "order_id": "orderid", "tracking": "1Z..." }
2190+
count: 2
2191+
data:
2192+
- id: "evt_123"
2193+
destination_id: "des_456"
2194+
topic: "user.created"
2195+
time: "2024-01-01T00:00:00Z"
2196+
successful_at: "2024-01-01T00:00:05Z"
2197+
metadata: { "source": "crm" }
2198+
data: { "user_id": "userid", "status": "active" }
2199+
- id: "evt_789"
2200+
destination_id: "des_456"
2201+
topic: "order.shipped"
2202+
time: "2024-01-02T10:00:00Z"
2203+
successful_at: null
2204+
metadata: { "source": "oms" }
2205+
data: { "order_id": "orderid", "tracking": "1Z..." }
2206+
next: ""
2207+
prev: ""
21012208
"404":
21022209
description: Tenant or Destination not found.
21032210

0 commit comments

Comments
 (0)