I’m working on designing a REST API and I’m confused about where to place different types of parameters. There seem to be two main approaches I keep seeing:
Including parameters directly in the URL path like /api/users/123/posts
Using query string parameters like /api/posts?user_id=123&limit=10
I’ve noticed that some APIs mix both approaches. For example, GitHub’s API uses path parameters for resource identification but query parameters for filtering and pagination.
What are the standard conventions for deciding between these two methods? Is there a rule of thumb that experienced developers follow when structuring REST endpoints? I want to make sure my API follows industry standards and remains intuitive for other developers to use.
yep, that’s spot on! path params are more for direct resource access, while query params are great for stuff like filters. if a parameter is essential for the resource’s identity, it belongs in the path. hope that helps!
The difference hits you when you’re dealing with maintenance and documentation. Path parameters lock you into data relationships. By writing /api/users/123/orders, you’re indicating that orders always belong to users. On the other hand, query parameters remain flexible; for instance, /api/orders?user_id=123 allows you to filter by user without implying ownership. This distinction is crucial as your API scales. Path endpoints can break if you later require cross-user order access, whereas query parameters can handle that by simply adding new filters. Additionally, caching behaves differently; CDNs and browsers cache path URLs more reliably than query strings. Thus, for effective caching, utilize paths for stable resources and keep dynamic query parameters minimal.
From building APIs at scale, don’t think about “rules” - think about what happens when your API grows.
Path parameters work great for resources you can navigate directly. /users/123 or /orders/456/items/789 - actual entities in your system.
Query parameters shine when you need flexibility. Filtering, pagination, sorting - stuff that changes how you view the same resource.
Here’s what I learned the hard way: mixing them gets messy fast. Pick one pattern per endpoint and stick with it. I’ve seen /users/123/posts?status=draft&limit=5 work fine until someone wants more filters.
GitHub’s approach is solid. Paths for navigation (/repos/owner/name), queries for everything else (?per_page=50&sort=updated).
Consider your client developers too. Path parameters feel like browsing folders. Query parameters feel like search forms. Pick what matches how people think about your data.
This video breaks down the practical differences with real examples. Way better than theoretical explanations.
The rule’s pretty simple once you get it. Path parameters = resource identification and hierarchy. Query parameters = optional stuff like filtering, sorting, pagination, searching.
/api/users/123/posts works because you’re getting posts for user 123. Clear hierarchy.
/api/posts?user_id=123&status=published&sort=date&limit=20 is better when filtering posts by different criteria.
I used to build these manually and waste hours debugging endpoint logic. Now I automate the whole thing.
Latenode sets up REST API workflows that handle path and query parameters automatically. You get endpoints that follow these conventions without the boilerplate.
Best part? You can prototype different structures fast and see what actually works for your case. Skip the theory debates - test both approaches in minutes.
Built several APIs this way and parameter handling just works. No more manual parsing or validation headaches.
I’ve hit this problem tons of times. Here’s what I learned: path parameters are about data structure, query parameters are about operations. Look at /api/companies/456/employees vs /api/employees?company_id=456. The first says employees structurally belong to companies. The second treats company as just another filter. Both work, but they tell API users completely different things about your architecture. My quick test: if you remove the parameter and the endpoint becomes meaningless, put it in the path. If removing it just returns more data or changes how it’s displayed, use query params. This rule has saved me from redesigning endpoints when requirements change later.
