CODEWITHSUNDEEP
restspring-mvcapi-designrestful-url
PeakGen
PeakGen

Reputation: 23035

RESTFUL API: Using path parameters vs query parameters

First, I do know path parameters need to be used when you are pointing at a resource and query parameters are meant to be used when you define something that can add a "property" (or change in time).

However, let's assume I need to get data belong to a user.

In this case, I am a fan of writing the REST API URL like this.

https://mylink/user/getbyid

And not

https://mylink/user/get

In the way I write the REST API, I will call the URL like /user/getbyid?id=1. In the way, I do not write the API, you will call it /user/get/1.

Since I write my API calls like /user/getbyid, /user/getbyname, /user/getbyuid I rarely use path parameters. 99% of the time I am using query parameters.

Considering the way I write my API calls, am I going against the best practices? Or is what I do right or ignorable?

Upvotes: 5

Views: 16741

Answers (2)

Nitin Srivastava
Nitin Srivastava

Reputation: 1424

The best practices to design a REST API to perform the basic CRUD (create, read, update, delete) operations is to use a combination of HTTP methods GET, POST, PUT, PATCH, and DELETE, URL and/or parameter(s).

Assuming you want to design a REST API to perform a CRUD operation for a user

1. Create

To perform create, design an endpoint /users with the POST HTTP method.

# HTTP method URL parameters
POST https://<yourdomain>/users, { first_name: "Peak", last_name: "Gen"}

2. Read

To perform Read, design an endpoint /users/<id> with the GET HTTP method.

# HTTP method URL parameters
GET https://<yourdomain>/users/1

2. Update

To perform Update, design an endpoint /users/<id> with PUT or PATCH HTTP method.

# HTTP method URL parameters
PUT https://<yourdomain>/users/1, { first_name: "Nitin", last_name: "Sri"}
**2. DELETE**

To perform Delete, design an endpoint /users/<id> with the DELETE HTTP method.

# HTTP method URL parameters
DELETE https://<yourdomain>/users/1

If you notice, the same URL is being used in Read, Update and Delete while their HTTP methods are different. It means the same URL routes to different actions based on their HTTP methods.

Read more about a REST API.

Upvotes: 0

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57377

I do know path parameters need to be used when you are pointing at a resource and query parameters are meant to be used when you define something that can add a "property" (or change in time).

That's not actually right. You are welcome to encode information into either the path or the query as you prefer; the machines don't care, as long as your identifiers are consistent with the production rules defined in RFC 3986.

The "resource identifier" includes both the path and the query_part.

Since I write my API calls like /user/getbyid, /user/getbyname, /user/getbyuid I rarely use Path parameters. 99% of the time i am using Query parameters.

Yup, that's fine.

Considering the way I write my API calls, am I going against the best practices? Or is what I do right or ignorable?

Ignorable, I'd say. Resource identifiers are a lot like variable names; people can spend hours arguing about variable names, and the machines don't care. The same is true of resource identifiers.

Could these identifiers be improved? I think so; the key idea being that we're identifying a resource, rather than identifying the implementation details of how the resource is implemented. The identifier is, in a sense, the "name of the document".

Removing the getby... path segment would also be fine.

/users?id=1
/users?name=bob
/users?uuid=469149ae-ecc6-4652-b094-17c211ff58ef

... but, depending on your routing implementation, disambiguating those three resources might be clumsy. Adding additional path segments to make the routing easier is fine.

Upvotes: 3

Related Questions