REST API url设计

Question

I have a REST API that has a database with table with two columns, product_id and server_id , that it serves product_ids to specific servers which request the data(based on the server_id from table). Let's say I have three servers with server_ids 1,2 and 3.

My design is like this: /products/server_id/1 and with GET request I get json list of product_ids with server_id = 1, similarly /products/server_id/2 would output list of product_ids for server_id = 2 .

Should I remove these routes and make a requirement to send POST request with instructions to receive product_ids for specific server_id in /products route only?

For example sending payload {"server_id":1} would yield a response of list of product_ids for server_id = 1 .

Answer 1

Should I remove these routes and make a requirement to send POST request with instructions to receive product_ids for specific server_id in /products route only?

Not usually, no.

GET communicates to general purpose components that the semantics of the request message are effectively read only (see "safe" ). That affordance alone makes a number of things possible; for instance, spiders can crawl and index your API, just as they would for a web site. User agents can "pre-fetch" resources, and so on.

All of that goes right out the window when you decide to use POST.

Furthermore, the URI itself serves a number of useful purposes - caches use the URI as the primary key for matching a request. Therefore we can reduce the load on the origin server by re-using representations have have been stored using a specific identifier. We can also perform magic like sticking that URI into an email message, without the context of any specific HTTP request, and the receiver of the message will be able to GET that identifier and fetch the resource we intend.

Again, we lose all of that when the identifying information is in the request payload, rather than in the identifier metadata where it belongs.

That said, we sometimes do use the payload for identifying information, as a work around: for example, if we need so much identifying information that we start seeing 414 URI Too Long responses, then we may need to change our interaction protocol to use a POST request with the identifying information in the payload (losing, as above, the advantages of using GET).

An online example of this might be something like an HTML validator, that accepts a candidate document and returns a representation of the problems found. That's effectively a read only action, but in the general case an HTML document is too long to comfortably fit in the target-uri of an HTTP request.

So we punt.

In a hypermedia api , like those used on the world wide web, we can get away with it, because the HTTP method to use is provided by the server as part of the metadata of the form itself. You as the client don't need to know the server's preferred semantics, you just need to know how to process the form data.

For instance, as I type this answer into my browser, I don't need to know what the target URI is, or what HTTP method is going to be used, because the browser already knows what to do (based on the HTML and whatever scripts are running "on demand").

Answer 2

In REST APIs, POST requests should only be used in order to create new resource, so in order to retrieve data from server, the best practice is to perform a GET request.

If you want to load products 1,2,4,8 on server 9 for example, you can use this kind of request:

GET https://website/servers/9/products/1,2,4,8

On server side, if products value contains a coma separated list, then return an array with all results, if not return just an array with only one item in order to keep consistency between calls.

In case you need to get all products, you can keep only the following url:

GET https://website/servers/9/products

As there is no id provided in products parameter, then the server should return all existing products for requested server parameter.

Note: in case of big amount of results, they must by paginated.