Skip to content

Commit e7507ae

Browse files
devalogdevalog
authored
Revamp Auto Pagination page (#83)
1 parent 41868e8 commit e7507ae

File tree

1 file changed

+86
-92
lines changed

1 file changed

+86
-92
lines changed

‎fern/products/sdks/guides/configure-auto-pagination.mdx‎

Lines changed: 86 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -3,105 +3,30 @@ title: Configure Auto Pagination
33
description: Paginate through API responses easily with offset, cursor, and link-based pagination.
44
---
55

6-
<Markdown src="/snippets/pro-callout.mdx" />
6+
Fern's auto pagination supports offset-based and cursor-based pagination schemes,
7+
providing SDK users with simple iterators to loop through all results instead of
8+
managing pagination complexity manually.
79

8-
Instead of forcing SDK users to learn the intricacies of your pagination system, Fern SDKs will return an iterator so that users can simply loop through all the results.
10+
This page describes how to configure auto pagination for your API endpoints.
911

10-
<Tabs>
11-
<Tab title="TypeScript" language="typescript">
12-
13-
When pagination for an endpoint is configured, the TypeScript SDK method
14-
will return a `Page<T>` where `T` is the underlying data type. The `Page<T>`
15-
will implement the `AsyncIterable` interface, allowing you to use it in a
16-
`for await` loop.
17-
18-
Below is an example method signature for a list endpoint:
19-
```typescript UsersClient.ts {10-13}
20-
import core from "../core";
21-
22-
export interface UsersClient {
23-
24-
/**
25-
* List all users
26-
* @param props
27-
* @returns A page of users
28-
*/
29-
list(
30-
request: ListUsersRequest = {},
31-
requestOptions: core.RequestOptions = {}
32-
): core.Page<User>;
33-
}
34-
```
35-
36-
And here is an example of how a user would use the `list` method:
37-
```typescript
38-
const response = await client.users.list();
39-
for await (const user of response) {
40-
console.log(user);
41-
}
42-
```
43-
44-
</Tab>
45-
<Tab title="Python" language="python">
46-
47-
When pagination for an endpoint is configured, the Python SDK method
48-
will return a `Pager[T]` (specifically a `SyncPager[T]` or an `AsyncPager[T]`) where `T` is the underlying data type. The `Pager[T]`
49-
will implement the `Generator` interface, allowing you to use it in a
50-
`for ... in` loop.
51-
52-
Below is an example method signature for a list endpoint:
53-
```python client.py {3-9}
54-
class UsersClient:
55-
56-
def list_with_cursor_pagination(
57-
self,
58-
*,
59-
page: typing.Optional[int] = None,
60-
page_size: typing.Optional[int] = None,
61-
request_options: typing.Optional[RequestOptions] = None,
62-
) -> SyncPager[User]:
63-
...
64-
```
65-
66-
And here is an example of how a user would use the `list` method:
67-
```python
68-
for user in client.users.list(page=1, page_size=10):
69-
print(user)
70-
```
71-
72-
or if the user is leveraging the asynchronous client:
73-
```python
74-
async for user in await client.users.list(page=1, page_size=10):
75-
print(user)
76-
```
77-
</Tab>
78-
</Tabs>
79-
80-
### Supported pagination types
81-
82-
Fern supports the following pagination schemes:
12+
## Setting up auto pagination
8313

84-
| Pagination Scheme | Supported |
85-
|-------------------|--------------------------------------------------|
86-
| Offset-based | <Icon icon="check" color="#84B060" /> |
87-
| Cursor-based | <Icon icon="check" color="#84B060" /> |
88-
| Link-based | |
14+
To configure auto pagination, specify the dot-access path to the related request
15+
or response property in the `x-fern-pagination extension` (OpenAPI) or `pagination`
16+
field (Fern Definition).
8917

90-
#### Configuration
18+
For example, if results of `my_nested_object` are located in the subfield
19+
`inner_list`, the dot-access path would be `results:
20+
$response.my_nested_object.inner_list`.
9121

92-
Annotate the desired paginated endpoint with the `x-fern-pagination` extension.
93-
For these fields, you can simply specify the dot-access path to the related request or response property.
94-
95-
For example, should the results of the following object be found in the subfield `inner_list`, you would specify `results: $response.my_nested_object.inner_list`.
96-
97-
```yaml
22+
```yaml {7-10}
9823
MyResponseObject:
9924
type: object
10025
properties:
10126
my_nested_object:
10227
type: object
10328
properties:
104-
inner_list:
29+
inner_list: # location of results
10530
type: array
10631
items:
10732
$ref: '#/components/schemas/MyObject'
@@ -111,7 +36,7 @@ MyResponseObject:
11136
<Tabs>
11237
<Tab title="OpenAPI">
11338
<CodeBlocks>
114-
```yaml Offset
39+
```yaml Offset {6}
11540
...
11641
paths:
11742
/path/to/my/endpoint:
@@ -121,7 +46,7 @@ paths:
12146
...
12247
```
12348

124-
```yaml Cursor
49+
```yaml Cursor {8}
12550
...
12651
paths:
12752
/path/to/my/endpoint:
@@ -138,7 +63,7 @@ paths:
13863
<Tab title="Fern Definition">
13964
<CodeBlocks>
14065

141-
```yaml Offset
66+
```yaml Offset {6}
14267
service:
14368
endpoints:
14469
listWithOffsetPagination:
@@ -147,7 +72,7 @@ service:
14772
results: $response.data
14873
```
14974
150-
```yaml Cursor
75+
```yaml Cursor {7}
15176
service:
15277
endpoints:
15378
listWithCursorPagination:
@@ -161,5 +86,74 @@ service:
16186
</Tab>
16287
</Tabs>
16388
89+
## Generated SDK Usage
90+
<Tabs>
91+
<Tab title="TypeScript" language="typescript">
92+
93+
Once you've configured pagination for an endpoint, Fern generates a TypeScript
94+
SDK method that returns a `Page<T>` where `T` is the underlying data type. The
95+
`Page<T>` will implement the `AsyncIterable` interface, allowing your users to
96+
use it in a `for await` loop.
97+
98+
Example generated method signature:
99+
```typescript UsersClient.ts {10-13}
100+
import core from "../core";
101+
102+
export interface UsersClient {
103+
104+
/**
105+
* List all users
106+
* @param props
107+
* @returns A page of users
108+
*/
109+
list(
110+
request: ListUsersRequest = {},
111+
requestOptions: core.RequestOptions = {}
112+
): core.Page<User>;
113+
}
114+
```
115+
116+
Example of how users would call the `list` method:
117+
```typescript
118+
const response = await client.users.list();
119+
for await (const user of response) {
120+
console.log(user);
121+
}
122+
```
123+
124+
</Tab>
125+
<Tab title="Python" language="python">
126+
127+
Once you've configured pagination for an endpoint, Fern generates a Python SDK
128+
method that returns a `Pager[T]` where `T` is the underlying data type. The
129+
`Pager[T]` will implement the `Generator` interface, allowing your users to
130+
use it in a `for ... in` loop.
164131

132+
Example generated method signature:
133+
```python client.py {3-9}
134+
class UsersClient:
135+
136+
def list_with_cursor_pagination(
137+
self,
138+
*,
139+
page: typing.Optional[int] = None,
140+
page_size: typing.Optional[int] = None,
141+
request_options: typing.Optional[RequestOptions] = None,
142+
) -> SyncPager[User]:
143+
...
144+
```
145+
146+
Example of how users would call the `list` method:
147+
```python
148+
for user in client.users.list(page=1, page_size=10):
149+
print(user)
150+
```
151+
152+
or if the user is leveraging the asynchronous client:
153+
```python
154+
async for user in await client.users.list(page=1, page_size=10):
155+
print(user)
156+
```
157+
</Tab>
158+
</Tabs>
165159

0 commit comments

Comments
 (0)