RESTFUL API: Using path parameters vs Query parameters-CodePudding

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 what I do is right or ignorable?

CodePudding user response：

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 what I do is 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.

CodePudding user response：

The best practices to design a REST API to perform the basic CRUD (Create, Read, Update, Delete) operations, use a combination of HTTP methods GET POST PUT PATCH DELETE, URL and/or parameter(s).

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

1. Create

To perform create, design an endpoint /users with 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 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 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. Means the same URL routes to different actions based on their HTTP methods.