How can you design an API to retrieve addresses with efficient pagination and filtering?

How can you design an API to retrieve addresses with efficient pagination and filtering?

• A. Use REST with limit/offset or cursor-based pagination, support filters on country, city, postal_code, address_type, and a search query, and provide total counts and sorting options.
• B. Use XML with page tokens and heavy nested structures.
• C. Use a single endpoint returning all addresses with no pagination.
• D. Use REST but only allow page numbers with fixed page sizes.

Answer: (B)

Efficient pagination and filtering in an address API rely on a REST-style design that lets clients fetch results in pieces and narrow them down quickly. The best approach is to expose an addresses resource with pagination controlled by either limit/offset or a cursor, and to offer filters for attributes like country, city, postal_code, and address_type, plus a free-text search option. This gives clients precise control over what they retrieve, minimizes data transfer, and keeps responses fast as the dataset grows. Including total counts helps clients know how many matches exist, and providing deterministic sorting ensures stable, repeatable pages.

Why this fits well: limit/offset is simple and cache-friendly for many clients, while cursor-based pagination can be more reliable for large datasets where items might be added or removed between requests. Filtering on specific fields accelerates queries by allowing the database to use indexes, and a search query supports user-friendly discovery. Sorting options prevent ambiguity in pagination results, so successive pages remain consistent even as new addresses are added.

Why the other approaches don’t fit as well: using XML with heavy nested structures adds parsing overhead and bloats the payload, making responses slower and less ergonomic for clients. Returning all addresses in a single endpoint with no pagination is not scalable and can overwhelm clients and networks. Restricting the API to page numbers with fixed page sizes reduces flexibility and can lead to inefficiencies or uneven page results as data changes.