Wrapping a messy API

A wrapper hides paging, retries, and errors behind one function that returns typed records.

Lesson 41 of 622 min read

The problem

Why it matters

Without it

Each tool calls the raw API on its own. Paging, rate limits, and odd responses are repeated in every tool.

With it

One wrapper handles paging, retries, and errors. Each tool gets a clean list of records with known types.

How it works

Each page gives items and a next page
A paged API returns part of the list and the number of the next page. The wrapper keeps asking until the next page is null. Page 1 holds A-1 and A-2, and it points to page 2.
Call Reply Next page
Page 1 A-1, A-2 2
Page 2, try 1 null, rate limited not known
Page 2, try 2 A-3 none
The calls the wrapper makes to read every order.

Call	Reply	Next page
Page 1	A-1, A-2	2
Page 2, try 1	null, rate limited	not known
Page 2, try 2	A-3	none

A rate-limited call is retried

A null reply means the API refused the call for now. The loop tries the same page again, up to three attempts in total. The second attempt on page 2 works.

Try 1null, rate limited
Try 2A-3, ok

The attempts on page 2.

let result: string[] | null = null;for (let attempt = 1; attempt <= 3 && !result; attempt++) {  result = attempt === 1 ? null : ["A-3"];  const label = result ? "ok" : "null";  console.log("attempt " + attempt + ": " + label);}

Output

attempt 1: null
attempt 2: ok

Failure after three attempts is an error
If all three attempts fail, the wrapper throws an error that names the page. An empty list would look like a real result with no orders. The error lets the caller report the failure instead.
```
try {  const result: string[] | null = null;  if (!result) throw new Error("Page 2 failed");} catch (error) {  console.log((error as Error).message);}
```
Output
```
Page 2 failed
```
Typed items reach the tools
The wrapper returns a plain list of strings. Tools built on it never see raw API replies or null values. The list joins into one line, as the full program shows.
- A-1string
- A-2string
- A-3string
The list that the wrapper returns to a tool.

Full code

Read the program

See the full code

Common mistakes

What goes wrong

Retrying forever. Use a fixed number of attempts, then report the failure.
Hiding a failure as an empty result. The model would then answer as if no data exists.
Stopping at a fixed page count. Stop when the API says there is no next page.

Use it when and skip it when

Is it the right tool?

Use it when

The API is paged, slow, or sometimes rate limited.
Several tools call the same API.

Skip it when

The API returns one small response, with no paging and no limits.

Words to know

Terms in this lesson

Pagination: Splitting a long list into pages that are fetched one at a time.
Rate limit: A cap on how many requests a client may send in a time window.
Retry: Trying the same request again after a failure.
Wrapper: Code that hides a raw API behind simpler functions.

Wrapping a messy API

Each page gives items and a next page

A rate-limited call is retried

Failure after three attempts is an error

Typed items reach the tools