REST endpoint to show a preview before POSTing

Question

I'm designing a new web application which is powered by a REST backend and HTML+JS frontend.

There's one POST method on it to change one entity (let's call Config), that has several side effects in the state of many elements of the application. Let's suppose the POST is performed this way:

POST /api/config BODY {config: ....}

Because of this, I would like to show a preview before those changes are made, for the end user to be able to notice what's going to change.

The thing I first thought about is to make a GET endpoint for the preview, sending the body of the new state of the entity. This way:

GET /api/preview/items BODY {config: ....}

Might show the new state for the items with the new configuration.

GET /api/preview/sales BODY {config: ....}

Might show the new state for the sales with the new configuration.

It seems a good idea to use the GET verb as I'm not altering the state of the application. However, the use of a request body with GET requests seems to be discouraged.

Is there any good practice about this? Other choice might be to store the config as a draft with one method and display the results with others, but it would require an additional step and having to manage the drafts in the server:

POST /api/preview/config BODY {config: ....}

GET /api/preview/items?idPreviewConfig=1

Answer 1

This is too domain-specific to have a native support in HTTP.

Instead, you may do one of the following:

1. Have a POST /api/config/preview. At server side, the application will know that it shouldn't modify the actual configuration, but combine the actual one with the one you posted, and return the result indicating what was changed.

   Later, if the user is satisfied with the result, she will perform a POST /api/config containing the same payload as in the previous request. This will effectively overwrite the configuration.

   The benefit of this approach is that you'are not making any breaking changes to the current API. Clients who don't need the preview feature would still be able to update the entries as they did before.

   The drawback is that when the body is large, it would mean that it would be needed to send it twice to the server. If this is your case, you may use the next approach.

2. Have a POST /api/config/prepare which remembers what was sent in a temporary record and returns two things: the ID of the temporary record (for instance 12345) and the preview of the changes.

   If the user is satisfied with the result, she will perform a POST /api/config/commit/12345 to definitively store the changes. If not, the temporary record may be kept for some time, and then discarded by a cron job.

   The benefit is that, here again, you may keep the original POST /api/config intact, and the clients which don't need a preview will not break.

   The drawbacks are that (1) handling the removal of temporary records can be tricky (what makes you think that one hour is enough? What if ten minutes later, you run out of memory? How clients handle a HTTP 404 when doing a commit of a record which expired?) and that (2) two-steps submission of a record may be more complicated than it needs to be.

3. Move the preview logic on client side.

Answer 2

The point of using specific HTTP verbs for different api calls in REST is to leverage the existing HTTP mechanics and expectations.

Using a GET in this case seems to go against both.

A. The client needs to include a body with a GET? unexpected

B. The server returns a different response to a get depending on the body? breaks spec and caching mechanics

If you are struggling with RESTful questions, my rule is to ask myself.

"How is this better than just using POST for everything?"

Unless there is an immediate and obvious benefit, go with the Just Use POST Stupid (JUPS) strategy

Answer 3

You can send a header that indicates to the server "do not persist this, only show me what the result would be if you did". E.g.

POST /api/config HTTP/1.1
Host: api.mysite.com
Content-Type: application/json
Persistence-Options: simulate

{
   "config": {
      "key": "value"
   }
}

To which the server could respond:

HTTP/1.1 200 OK
Persistence-Options: simulated
Content-Type: application/json

-- preview --

---

Note that, if you use a Unit of Work based O/RM and/or per-request transactions with your DB you can easily implement this functionality for all your endpoints without requiring work on any particular endpoint: If a request comes in with that option, roll back the transaction / unit-of-work instead of commiting it.

Answer 4

I would suggest treating this the same way you treat searches. I would set up a POST endpoint at /api/config/preview which CREATES a new preview. Then I would set up a PUT or PATCH endpoint at api/config depending on whether you intend to edit the current configuration, or simply replace the entire config (presumably in the former case you would be sending the preview you just created).

Answer 5

Along with the other good answers, another option could be to post the config like mentioned, and have a rollback process available too. I think, like Agile methodology, it's better to be less scared of changes by having more granular, repeatable, and tested procedures, and this would give you a backup when you need it, reducing the risk to little or none, depending on the application.

Then again, if you may have configuration errors affecting the whole system, you would like to handle it more actively, and if that's the case, why not just put the effort into previewing the changes at that point, from a server or client perspective. Although, I can see how this previewing feature could be more expensive to develop, at the uses cases have their own set of disparate steps to follow and test.

Answer 6

RFC6648 deprecates new X- constructs so I must vote against the idea to send a new header-field. REST is a architecture style, what we talk about is RESTful - but lets ignore that for this moment.

Because REST is Representative (and a simulation has no representation in the reality) and Stateful (and a simulation is not a state until its committed) we must have a new scope, like a simulation-scope. But we must call it emulation instead of simulation because simulation includes the process of simulation but stateful means we have a standing state, a ideal solution of a simulation: a emulation. So we need to call it emulation in the URL. This might also be a good solution:

GET  /api/emulation - 200 OK {first:1, last:123}
POST /api/emulation/124 - 200 OK
GET  /api/emulation/124/config - 200 OK {config:{tax:8}}
PUT  /api/emulation/124/config {config:{tax:16}} - 200 OK {config:{tax:16}}
GET  /api/emulation/124/items - 200 OK [first:1, last: 3000]
GET  /api/emulation/124/items/1 - 200 OK {price:1.79, name:'Cup'}
--- show emulation ---
--- commit emulation ---
PUT /api/config {config:{tax:16}}
DELETE /api/emulation/124 - 200 OK

There is another approach .... you might noticed having alot of requests from the HTML/JavaScript-client may produce the Too many requests, what reaches the limit of about 17 requests at the same time (have a look at this page). You can swap the usage of REST and instead of deliver lame object-states you can deliver rich user-specific page-states. Example:

GET /user/123/config - 200 OK {user:'Tim', date:3298347239847, currentItem:123, 
                  roles:['Admin','Customer'], config:{tax:16}, unsavedChanges:true, ...}

Kind Regards