I am puzzled about the conventions to use for implementing a REST service: as far as I understand, if the service does not change anything about the state of the server, a GET request should be used.
But if the service is expected to accept some data and to give back a result for that data, a GET request cannot be reasonable be used because it cannot have a request body (according to some pages I have read) or if it does have a request body, it should not influence the semantics of the service. What is the correct way to deal with this?
Also, what is the best strategy to return metadata about a service and in what way? For example, if the service accepts a POST request to process my data, would using GET to the same endpoint be a good convention to return metadata about the service?
UPDATE: examples for the kind of service I have in mind: send a collection of documents and get back a matrix of document similarities, send a large CSV file and get back some kind of statistical analysis .. that sort of thing. Essentially the services calculates f(x) where x tends to be a large file.
Related
Basically if there is fresh data in the database, I will directly read that data, otherwise if the data is older, I would be computing new data to insert, and then read that inserted data. Which is better, putting that logic under one POST endpoint or splitting the insert part under a POST endpoint, and the get part under a GET endpoint, then calling the POST endpoint which would redirect to the GET endpoint?
Assuming that "computing new data to insert" doesn't involve reading information out of the HTTP request body, you should normally use GET here.
We choose HTTP methods based on the semantics of the request ("give me the current representation of the resource") not on the implementation details of the request handler.
If you don't need to send the data in the request body, then use one endpoint and use GET for it. A similar question involves counting reads of a resource, which has a side effect too, still we use GET for retrieving the representation of the resource along with read count, because the operation is about data retrieval not data sending.
Another reason for using GET, that you will be able to use caching features this way, and using if-modified-since or if-none-match will make what you want a lot easier.
I have a REST API in which I would like to add an endpoint that runs an algorithm and returns a result. Let's assume the algorithm is fast enough that this can be done synchronously. However, the result can be large.
Option A
I treat the result of the algorithm as a "resource". I could implement the following
POST /api/my-result
This creates a new result by running the algorithm. The inputs to the algorithm are in the request body. The response contains the id or some other identifiable representation of the result.
GET /api/my-result//?view=table
This allows the client to get a table representation of the result. Similarly there could be additional views, filters, etc. that could be implemented the same way.
However, this requires me to persist the results in a database. There are two issues: (a) the results can be large, and (b) the client often runs the algorithm several times with different inputs before deciding to "keep" one of the results - so ideally I only want to store the final result in the database.
Option B
POST /api/my-algorithm/
This accepts the parameters of the algorithm in the request body and returns the result in the response body
POST /api/my-result-table-view
This accepts the result in the request body and returns a response that transforms the representation of the result into a table view. The reason it is not GET /api/my-result//?view=table is because the client needs to be able to call this on results that are not persisted. The "table view of the result" is the resource that is created here.
Similarly, I could implement each view of the result as a separate endpoint.
POST /api/my-result
This creates a new result (without running the algorithm). For example, if the result is an image, this POST request may accept the image as a file upload and simply store it. The client calls POST /api/my-algorithm/ repeatedly, and when they are happy with the result, they call this endpoint to create the result.
I believe Option A is the more "RESTful" way, but with the overhead of persisting all results.
Which option do you recommend? Can Option B be implemented differently to make it more "RESTful"? Is there a way I can create a resource without actually persisting it in the database (maybe in a cache)? If you propose the caching route, please include more explanation as I'm not familiar with how that would be implemented.
(If it is relevant, I'm using DRF for implementing the API)
I want to retrieve data about a bunch of resources. Let's say an Array of book id and the response is JSON Array of book objects. I want to send the request payload as JSON to the server.
Should I use GET and POST method?
Note:
I don't want to make multiple GET request for each book ID.
POST seems to be confusing as it is supposed to be used only when the request creates a resource or modifies the server state.
I want to retrieve data about a bunch of resources. Let's say an Array of book id and the response is JSON Array of book objects.
If you are thinking about passing the array of book id as the message body of the HTTP Request, then GET is a bad idea.
A payload within a GET request message has no defined semantics; sending a payload body on a GET request might cause some existing implementations to reject the request.
You should use POST instead
POST seems to be confusing as it is supposed to be used only when the request creates a resource or modifies the server state.
That's not quite right. POST can be used for anything -- see GraphQL or SOAP. But what you give up by using POST is the ability of intermediate components to participate in the conversation.
For example, for cases that are effectively read-only, you would like to use a safe method, because that allows pre-caching optimization, and automated retry of lost responses on an unreliable network. POST doesn't have extra semantic constraints, so you lose out.
What HTTP really wants is that you GET using the URI; this can be done in one of two relatively straightforward ways:
POST the ids to the server, to create a new resource (meaning that the server retains for itself a copy of the list of ids), and receive a new resource identifier back in exchange. Then GET using this new identifier any time you want to know the current representation of the results.
Encode the information you need into the URI itself. Most commonly, this is done using the query part of the URI, although that isn't strictly necessary. The downside here is that if the URI encoded representation of the array of ids is very long, you may have trouble with some implementations that enforce arbitrary URI limits.
There aren't always great answers:
The REST interface is designed to be efficient for large-grain hypermedia data transfer, optimizing for the common case of the Web, but resulting in an interface that is not optimal for other forms of architectural interaction.
If I understand correctly, you want to get a list of all of the items in a list, in one pull. This would be possible using GET, as REST returns the JSON it can by default be up to 100 items, and you can get more items if needed by specifying $top.
As far as writing back or to the server, POST would be what your looking for, this to my understanding would need to be one for one.
you are going to use a GET-Request and put your request-data (book-id array) in the data-section of your ajax (or whatever you're going to use) request. See How to pass parameters in GET requests with jQuery
Search - request contains query parameters e.g. search term and pagination values. No changes/data is persisted to backend.
I currently use GET with query parameters here.
Data conversion - request contains data in format A and server sends data in format B. No changes/data is persisted to backend.
I currently use POST with request parameters here.
For your Data Conversion use case (which seems to be more of a function that working with a representation of something on the server), the answer is more grounded in higher-level HTTP verb principles than RESTful principles. Both cases are non-idempotent: they make no changes to the server, so GET should be used.
This question has a good discussion of the topic, especially this comment:
REST and function don't go well together. If an URL contains function, method, or command, I smell RPC – user1907906
Search - request contains query parameters e.g. search term and pagination values. No changes/data is persisted to backend.
If the request is supposed to generate no changes on the back end, then you are describing a request which is safe, so you should choose the most suitable safe method - GET if you care about the representation, HEAD if you only care about the meta data.
Data conversion - request contains data in format A and server sends data in format B. No changes/data is persisted to backend.
Unless you can cram the source representation into the URL, POST is your only reasonable choice here. There is no method in HTTP for "this is a safe method with a payload".
In practice, you could perhaps get away with using PUT rather than POST -- it's an abuse of the uniform interface, but one that allows you to communicate at least the fact that the semantics are idempotent. The key loophole is:
there is no guarantee that such a state change will be observable, since the target resource might be acted upon by other user agents in parallel, or might be subject to dynamic processing by the origin server, before any subsequent GET is received. A successful response only implies that the user agent's intent was achieved at the time of its processing by the origin server.
I am working on a small client server program to collect orders. I want to do this in a "REST(ful) way".
What I want to do is:
Collect all orderlines (product and quantity) and send the complete order to the server
At the moment I see two options to do this:
Send each orderline to the server: POST qty and product_id
I actually don't want to do this because I want to limit the number of requests to the server so option 2:
Collect all the orderlines and send them to the server at once.
How should I implement option 2? a couple of ideas I have is:
Wrap all orderlines in a JSON object and send this to the server or use an array to post the orderlines.
Is it a good idea or good practice to implement option 2, and if so how should I do it.
What is good practice?
I believe that another correct way to approach this would be to create another resource that represents your collection of resources.
Example, imagine that we have an endpoint like /api/sheep/{id} and we can POST to /api/sheep to create a sheep resource.
Now, if we want to support bulk creation, we should consider a new flock resource at /api/flock (or /api/<your-resource>-collection if you lack a better meaningful name). Remember that resources don't need to map to your database or app models. This is a common misconception.
Resources are a higher level representation, unrelated with your data. Operating on a resource can have significant side effects, like firing an alert to a user, updating other related data, initiating a long lived process, etc. For example, we could map a file system or even the unix ps command as a REST API.
I think it is safe to assume that operating a resource may also mean to create several other entities as a side effect.
Although bulk operations (e.g. batch create) are essential in many systems, they are not formally addressed by the RESTful architecture style.
I found that POSTing a collection as you suggested basically works, but problems arise when you need to report failures in response to such a request. Such problems are worse when multiple failures occur for different causes or when the server doesn't support transactions.
My suggestion to you is that if there is no performance problem, for example when the service provider is on the LAN (not WAN) or the data is relatively small, it's worth it to send 100 POST requests to the server. Keep it simple, start with separate requests and if you have a performance problem try to optimize.
Facebook explains how to do this: https://developers.facebook.com/docs/graph-api/making-multiple-requests
Simple batched requests
The batch API takes in an array of logical HTTP requests represented
as JSON arrays - each request has a method (corresponding to HTTP
method GET/PUT/POST/DELETE etc.), a relative_url (the portion of the
URL after graph.facebook.com), optional headers array (corresponding
to HTTP headers) and an optional body (for POST and PUT requests). The
Batch API returns an array of logical HTTP responses represented as
JSON arrays - each response has a status code, an optional headers
array and an optional body (which is a JSON encoded string).
Your idea seems valid to me. The implementation is a matter of your preference. You can use JSON or just parameters for this ("order_lines[]" array) and do
POST /orders
Since you are going to create more resources at once in a single action (order and its lines) it's vital to validate each and every of them and save them only if all of them pass validation, ie. you should do it in a transaction.
I've actually been wrestling with this lately, and here's what I'm working towards.
If a POST that adds multiple resources succeeds, return a 200 OK (I was considering a 201, but the user ultimately doesn't land on a resource that was created) along with a page that displays all resources that were added, either in read-only or editable fashion. For instance, a user is able to select and POST multiple images to a gallery using a form comprising only a single file input. If the POST request succeeds in its entirety the user is presented with a set of forms for each image resource representation created that allows them to specify more details about each (name, description, etc).
In the event that one or more resources fails to be created, the POST handler aborts all processing and appends each individual error message to an array. Then, a 419 Conflict is returned and the user is routed to a 419 Conflict error page that presents the contents of the error array, as well as a way back to the form that was submitted.
I guess it's better to send separate requests within single connection. Of course, your web-server should support it
You won't want to send the HTTP headers for 100 orderlines. You neither want to generate any more requests than necessary.
Send the whole order in one JSON object to the server, to: server/order or server/order/new.
Return something that points to: server/order/order_id
Also consider using CREATE PUT instead of POST