2.3API usage patterns and constraints

An API is not an ideal window where "every call instantly returns everything." In real operation you always hit three constraints: how to learn of changes (polling vs. webhook), how to curb over-calling (rate limiting), and how to fetch large data in pieces (pagination). Ignore them and wasteful polling trips the rate limit (429), or you see only page one and wrongly conclude "the data is incomplete." This section covers the meaning of each constraint and the correct design/handling that matches it, as judgment.

2.3.1Webhooks and polling

• Polling has the client periodically call the API asking "changed yet?" It is simple to implement, but when changes are rare most calls come back empty, and raising the frequency approaches the rate limit. Hitting the API every second just to "learn of a change within a minute" is inefficient.
• A webhook is the reverse call: when an event occurs, the server sends an HTTP POST to the client's registered URL. The client just prepares a receiver (callback URL) and waits, receiving changes immediately and with low load. For "notify the instant an alert fires" or "wait for a rare state change," a webhook fits better than polling.
• The decision axes are change frequency, immediacy requirement, and whether you can expose a receiver. A webhook needs a reachable receiving endpoint and care for authenticity verification (signatures) and duplicate/out-of-order deliveries. Meanwhile a one-off list fetch or a synchronous query is fine as plain polling (request/response).

2.3.2Rate limiting and pagination

• Rate limiting caps calls per unit time. Exceeding it returns 429 Too Many Requests, usually with a Retry-After (seconds to wait) or X-RateLimit-Remaining (remaining calls) header. The correct response is to honor the instruction and then use exponential backoff (doubling the wait after each failure) to reduce frequency. Tightening retries is counterproductive.
• Pagination returns large result sets split across pages. Styles include offset (?limit=100&offset=200), a cursor pointing past the previous page's end, or a next link embedded in the response. The key is to not mistake page one for the whole set; you have all records only after iterating until there is no next (or the returned count is below the limit).

Suppose you are building a network-monitoring tool and implement "notify the on-call person the instant a device alert fires." The first implementation polls the alert API every 5 seconds for new alerts. In operation it immediately floods 429 Too Many Requests with Retry-After: 30. Thinking "remove the wait and poll even more tightly so nothing is missed" is entirely counterproductive—it hammers the rate limit further and worsens the 429. The right judgment is two-tiered. Short term, honor Retry-After and switch polling to exponential backoff (30s -> 60s -> 120s...) to fit calls within the limit. But fundamentally this use case is structurally ill-suited to polling—alerts are rare, yet for immediacy you repeat high-frequency empty calls. The docs show this API supports webhooks: on an alert it can POST a notification to your registered URL. So you switch the design, prepare a callback URL, and register a webhook; now a notification arrives only at the instant an alert fires, eliminating both the empty polls and the rate-limit problem. Separately, when fetching large data like the full device list, GET /devices?limit=100 returns with a next link, so you must iterate until next is gone to cover every device (do not see only page one and conclude "there are only 100"). The lesson: a 429 symptom is not something to force through by "removing the wait"—it is the judgment to match the design to the nature of the constraint (rate limit, polling inefficiency, page splitting): webhooks for instant notification, backoff for frequency, page iteration for full retrieval.

2.3.3Section summary

• A webhook is a reverse call (server->client POST) for rare changes/instant notifications; it eliminates both empty high-frequency polling and rate-limit pressure
• For rate limiting, honor Retry-After on a 429 and lower frequency with exponential backoff; tightening the interval is counterproductive
• With pagination, iterate until next (or a below-limit count) to obtain all records; page one is not the whole set