When creating a REST resource, must the representation of that resource be used?-CodePudding

As an example imagine a dynamic pricing system which you can ask for offers moving boxes from 1 place to another. Since the price does not exist before you ask for it it's not as simple as retrieving data from some data-base, but an actual search process needs to run.

What I often see in such scenario's is a request/response based endpoint:

POST /api/offers

{
  "customerId" : "123",
  "origin" : {"city" : "Amsterdam"},
  "destination" : {"city" : "New York"},
  "boxes": [{"weight" : 100},{"weight": "200"}]
}

201: 
{
  "id" : "offerId_123"
  "product" : {
    "id" : "product_abc",
    "name": "box-moving"
  }
  "totalPrice" : 123.43
}

The request has nothing to do with the response except that one is required to find all information for the other.

The way I interpret "manipulation of resources through representations" I think that this also goes for creation. Following that I would say that one should create the process of searching in stead:

POST /api/offer-searches

{
  "request" : {
    "customerId" : "123",
    "origin" : {"city" : "Amsterdam"},
    "destination" : {"city" : "New York"},
    "boxes": [{"weight" : 100},{"weight": "200"}]
  }
}

201: 
{
  "id" : "offerSearch_123"
  "request" : {
    "customerId" : "123",
    "origin" : {"city" : "Amsterdam"},
    "destination" : {"city" : "New York"},
    "boxes": [{"weight" : 100},{"weight": "200"}]
  }
  offers: [
    "id" : "offerId_123"
    "product" : {
      "id" : "product_abc",
      "name": "box-moving"
    }
    "totalPrice" : 123.43
  ]
}

Here the request and the response are the same object, during the process it's enhanced with results, but both are still a representation of the same thing, the search process.

This has the advantage of being able to "track" the process, by identifying it it can be read again later. You could still have /api/offers/offerId_123 return the created offer to not have to go through the clutter of the search resource. But it also has quite the trade-off: complexity.

Now my question is, is this first, more RPC like approach something we can even call REST? Or to comply to REST constraints should the 2nd approach be used?

CodePudding user response：

Now my question is, is this first, more RPC like approach something we can even call REST? Or to comply to REST constraints should the 2nd approach be used?

How does the approach compare to how we do things on the web?

For the most part, sending information to a server is realized using HTML forms. So we are dealing with a lot of requests that look something like

POST /efc913bf-ac21-4bf4-8080-467ca8e3e656
Content-Type: application/x-www-form-urlencoded

a=b&c=d

and the responses then look like

201 Created
Location: /a2596478-624f-4775-a490-09edb551a929
Content-Location: /a2596478-624f-4775-a490-09edb551a929
Content-Type: text/html

<html>....</html>

In other words, it's perfectly normal that (a) the representations of the resource are not the information that was sent to the server, but intead something the server computed from the information it was sent and (b) not necessarily of the same schema as the payload of the request... not necessarily even the same media type.

In an anemic document store, you are more likely to be using PUT or PATCH. PATCH requests normally have a patch document in the request-body, so you would expect the representations to be different (think application/json-patch json). But even in the case of PUT, the server is permitted to make changes to the representation when creating its resource (to make it consistent with its own constraints).

And of course, when you are dealing with responses that contain a representation of "the action", or representations of errors, then once again the response may be quite dissimilar from the request.

TL;DR REST doesn't care if the representation of a bid "matches" the representation of the RFP.

You might decided its a good idea anyway - but it isn't necessary to satisfy REST's constraints, or the semantics of HTTP.