Examples of path parameters

Everyone knows PayPal. PayPal creates billing agreements with companies. If you register with PayPal for a payment system, they provide you with a REST API for all your billing needs. The sample GET request for getting the information of a billing agreement looks like this: /v1/payments/billing-agreements/agreement_id.

Here, the resource query is with the path parameter. When the server sees this line, it interprets it as I got an HTTP request with a need for agreement_id from the billing agreements. Then it searches through the database, goes to the billing-agreements table, and finds an agreement with the given agreement_id. If that resource exists, it sends back a copy of the details in response (200 OK), or else it sends a response saying, "resource not found" (404).

Using GET, you can also query a list of resources, instead of a single one as in the preceding example. PayPal's API for getting billing transactions related to an agreement can be fetched with /v1/payments/billing-agreements/transactions. This line fetches all transactions that occurred on that billing agreement. In both instances, the data is retrieved in the form of a JSON response. The response format should be designed beforehand so that the client can consume it in the agreement.

Examples of query parameters are as follows:

• Query parameters are intended to add detailed information to identify a resource from the server. For example, imagine a sample fictitious API. Let's assume this API is created for fetching, creating, and updating the details of the book. A query parameter based GET request will be in this format: 

/v1/books/?category=fiction&publish_date=2017

• The preceding URI has a couple of query parameters. The URI is requesting a book from the books resource that satisfies the following conditions:
• It should be a fiction book
• The book should have been published in the year 2017

Get all the fiction books that are released in the year 2017 is the question the client is posing to the server. 

Path vs Query parameters—When to use them? It is a common rule of thumb that Query parameters are used to fetch multiple resources based on the Query parameters. If a client needs a single resource with exact URI information, it can use Path parameters to specify the resource. For example, a user dashboard can be requested with Path parameters, and fetch data on filtering can be modeled with Query parameters.