\n
Good API design is not about endpoints, it is about trust. If clients can guess what happens next, you did it right.
\n
\n\n
A morning with logs, coffee, and a stubborn feed
\n
I spent the morning watching our mobile app hit the feed endpoint like a woodpecker. New users keep scrolling, the app keeps asking for more, and somewhere between the fourth and fifth request the whole thing starts to feel shaky. Rate limits are getting tighter, Twitter just tightened theirs, and our servers do not love surprise storms. That is when pagination, sorting, and filtering stop being buzzwords and become the way you keep the lights on.
\n
Right now the web is full of fresh clients. iOS apps, Android apps, single page dashboards, cron jobs that sync at night. They all want data in slices they can handle. If your REST API returns a firehose with no handles, your clients will duct tape their own, and you will inherit the mess. Give them predictable pages, clear order, and flexible filters, and your support inbox gets a lot quieter.
\n\n
What broke last week, and what it taught me
\n
Last week a retailer wrote in. Their admin listed orders by newest first on desktop, but their warehouse app showed a different order. Same API, different defaults, frustrated staff. We fixed it by making sorting explicit, not assumed. We also shipped cursors for pagination so large result sets do not jump around. Small changes, big relief. The lesson is simple. Make the rules obvious, and write them once for every client to follow.
\n
The same story repeats across teams. Search results without filtering cause support tickets. Reports that cannot ask for a date range end up downloaded into spreadsheets where truth goes to get lost. You can keep this tidy with a few steady patterns that do not surprise people, even when your dataset grows.
\n\n
Deep dive one: Pagination that does not lie
\n
There are three common ways to page through results in a REST API. Each one trades simplicity for stability in a different way.
\n
- \n
- Page and per_page. Clients send page=3 and per_page=50. Easy to read and debug. Works well when the sort order is stable.
- Limit and offset. Clients send limit=50 and offset=100. Fine for small sets, but offset can get slow in some databases once tables grow.
- Cursor based. The server returns a token like next_cursor that points to the next slice. This keeps order stable while rows are added or removed, which is great for feeds and timelines.
\n
\n
\n
\n
Pick one, then make it predictable. Return metadata with every page. Include total when it is cheap, plus next and prev hints. Put page links in the Link header too, so clients can follow their nose. Keep default sizes safe for mobile networks, and publish a clear max per page so nobody asks for ten million rows by accident.
\n\n
Deep dive two: Sorting that makes sense
\n
Sorting needs to be explicit and boring. Let clients choose fields and direction, then stick to a list you support. A simple pattern is a single sort parameter that accepts a list of fields with direction markers, for example name:asc or created_at:desc. That reads well, avoids magic, and plays nice with logs.
\n
- \n
- Whitelist fields. Publish allowed sort fields. Reject the rest with a helpful error.
- Stable tie breakers. When two rows share the same value, add a secondary sort like id:asc. This prevents records from jumping between pages.
- Defaults are contracts. Document the default sort, and never change it without a version bump. Surprises cost teams time.
\n
\n
\n
\n
Small touch that helps a lot. Echo the applied sort back in the response. A tiny reminder in the payload keeps clients honest and helps when debugging.
\n\n
Deep dive three: Filtering that pulls its weight
\n
Filters do the heavy lifting between wild dumps and tight, useful results. Keep them consistent across resources to lower team guesswork.
\n
- \n
- Field equals. Support simple key equals value filters like status=pending or user_id=42.
- Ranges. Use pairs like created_at_from and created_at_to for time windows. This reads clean in URLs and docs.
- Sets. Allow repeated keys or comma lists for in queries, for example tag=blue and tag=green or tag=blue,green.
- Comparison words. For numbers and dates, support operators with words, like price_lt, price_gt, price_gte, price_lte. They are readable and avoid parser games.
- Case and accents. Be clear if text filters are case insensitive. Say it in the docs and be consistent.
\n
\n
\n
\n
\n
\n
Watch out for filter bombs. Add a max range for dates, a max set size, and a friendly error when someone asks for everything everywhere. Your database will thank you.
\n\n
A small promise to your future self
\n
We are shipping for phones that just got taller screens and for browsers with tabs that never close. Next month there will be a new client you did not plan for. If your API design makes pagination, sorting, and filtering steady and boring, that new client will still work on day one. Write the rules once, keep them obvious, and send them in every response. That is the kind of boring that scales.
\n
Action plan. Pick your paging style and document it. Add explicit sort with a whitelist. Give filters names that read like speech. Return clear metadata and link headers. Then watch your logs get calmer and your product team move faster.
\n\n