Menu

URI Parameter and Query parameters differences

Understanding the URI Parameter and Query Parameter

How many times were you wondered whether to use query parameter or URI parameter when designing an API. I had this question couple of times and I had to my research on this topic which I am sharing in this post.

As an API developer, you would have designed an API to get a collection of resource, filter the resource or do some action on an instance resource. It is important to understand when to use a query parameter and uri parameter. They both serve different purpose.

What is URI Parameter:

A URI is a resource identifier that uniquely identifies a specific instance of a resource. URI is Unique Resource Identifier as the name suggests, it should get a unique resource. The parameter which is part of the URL that is passed to get the unique resource is the URI parameter.

Example

Get an account with unique id 1234
/accounts/1234

JAX-RS example
@Path("/accounts/{account-id}")
public class UserResource {

        @GET
        @Produces("application/json")
        public String getAccount(@PathParam("account-id") String accountId) {
            ...
        }
    }
RAML Example
/accounts:
    get: 
      description: retrieve all accounts with a possibility to limit the number of accounts in the response.
      is: [paged, filterable]
      responses: 
        200:
          body: 
            type: account[]
            example: !include account-example/AccountsExample.raml
      
    /{externalId}:
      get:
        description: Retrieve an account by specifying the external Id
        responses: 
          200:
            body: 
              type: account
              example: !include account-example/AccountExample.raml
          404:
            body: 
              example: 
                message: Not account found for the external id

What is Query Parameter:

Query parameters are used to filter the collection resources type. The query parameters are passed at the end of the URL after a question mark to sort, filter or paginate the resource.

Example

Get the accounts which are in active state and limit it by 50 accounts

/accounts?status=active&limit=50

@Path("/accounts")
public class UserService {

    @GET
    @Path("/query")
    public Response getAccounts(
        @QueryParam("status") string status){
}}

RAML Example
#%RAML 1.0 Trait
queryParameters: 
  accountName:
    displayName: Account Name
    description: Filter accounts based on account name
    type: string
    required: false
    example: Pyramid Construction Inc
#%RAML 1.0 Trait
queryParameters:
  limit:
    displayName: Limit
    description: Specify the limit of accounts retrieved per page
    type: integer
    required: false
    example: 80
    default: 10
  offset:
    displayName: Offset
    description: Specify the page that you want to retrieve
    type: integer
    required: false
    example: 1
    default: 0

So, in a nutshell, use query paramter to filter the resources and use the URI parameter to get a unique resource.

Add comment