When to use @QueryParam vs @PathParam

java

api-design

rest-api

path-params

byAnton Shumikhin·Mar 12, 2025

Utilize @QueryParam for optional data in search filters: ?author=King. It enables search customization and flexibility.

// search for suspense thrillers kind of like asking the librarian for Stephen King's genre
getBooks(@QueryParam("genre") String genre) { ... }

Use @PathParam to directly point to a unique resource in the URL path: /users/112. It provides straight access to resources.

// you got a friend request! visiting a user's profile, like knocking on a specific door
@Path("/users/{id}") getUser(@PathParam("id") String id) { ... }

Pick @QueryParam for variety and freedom in data access, and @PathParam for focused and direct access to resources.

Making the right choice: Considering the necessities

Whether to go for @QueryParam or @PathParam depends on the specific information needs of the API call. Here are some factors to guide your decision:

Importance of data: Required or optional?

For required data that forms the resource's identity use @PathParam.
For optional data that fine-tunes your output, consider @QueryParam.

Drill down to the resource

In instances where resource uniqueness or hierarchical data is in play:

// getting the hang of the Dewey Decimal System to reach a specific library book
@Path("/books/{isbn}/editions/{editionId}") 
getEdition(@PathParam("isbn") String isbn, @PathParam("editionId") String editionId) { ... }

Sorting, filtering, and pagination

These are all excellent examples of where @QueryParam shines:

// telling the librarian you want horror novels by King, published after 1980
@Path("/books")
getBooks(@QueryParam("author") String author, @QueryParam("publishedAfter") Integer year) { ... }

Bookmarking vs caching

@PathParam is particularly useful for resource-intensive operations that benefit from caching or bookmarking.

// a user's profile, easy to bookmark for your daily internet stalking
@Path("/profiles/{profileId}")
getUserProfile(@PathParam("profileId") String profileId) { ... }

Striving for clarity

Keep your API design clean by maintaining distinct URL paths for resources using @PathParam and flexible tuning parameters using @QueryParam:

@Path("/products/{productId}") 
getProduct(@PathParam("productId") String productId, @QueryParam("reviews") Boolean includeReviews) { ... }

Reflecting on your parameters

Reflect on the function of your parameter: Does it navigate to a resource or customise the request?

Specifying attributes

When attribute specification is needed, @QueryParam handles multiple filter criteria with grace:

// playing detective and searching employees by department and role
@Path("/employees")
searchEmployees(@QueryParam("department") String department, @QueryParam("role") String role) { ... }

Learn from the best: Following successful API design patterns

Looking at established REST APIs can help you identify best practices:

Follow the leaders

APIs like Github and StackOverflow demonstrate how to use path and query parameters for effective API design.

Clear URL handlers

Using query parameters can decutter URL handlers, keeping the API simple for both users and developers.

Sub-resource access

@PathParam is especially useful when you need to reach a specific sub-resource within a resource hierarchy:

// Peeking at comments on a random blog post
@Path("/blog-posts/{postId}/comments")
getComments(@PathParam("postId") String postId) { ... }

Dynamic content and @QueryParam

@QueryParam is your go-to when you want to modify the page layout or content based on user actions or preference:

// Tailoring your dashboard view with selected widgets, like moving your furniture around on a whim
@Path("/dashboard")
getDashboard(@QueryParam("widgets") List<String> widgets) { ... }