REST : Request as a subset of Response

Question

I have come across numerous JSON over HTTP APIs that were suppose to be RESTful but I'm not sure if the following design is adhering to REST principals - Request model is used as a subset of Response model.

For example, POST /flight/inquiry Request :

{ 
   "flight_no":"2384B",
   "departure_time":78163918839123,
   "arrival_time":78163918889382,
   ...
}

Response :

{
  "request" : 
     { 
       "flight_no":"2384B",
       "departure_time": 78163918839123,
       "arrival_time": 78163918889382,
       ...
     }
  "status" : "ON TIME"
  "last_updated" :  7816391884313,
  ...
}

If we analyze this in terms of Richardson Maturity Model, I think it will not qualify for level 1 because there is no clear definition of a Resource. If we call 'Inquiry' as the resource here, the response should not have result on the inquiry such as status, last_updated, etc. Typically, it should respond with an inquiry_id (like 123) that can be passed to a second end point GET /flight/123/status. This approach, though is more aligned with REST principles (correct me if I'm wrong), developers tend to avoid it simply because it's easy to squeeze the same behavior in a single end point rather than two. My question is, are there consequences to ignoring REST principles in situations like these where it is simpler to take shortcuts?

score 1 · Accepted Answer · answered Feb 09 '20 at 13:44

I think your current understanding is suspect.

Using POST to request a representation of a resource isn't RESTful, because we have GET, which is more suitable.

It isn’t RESTful to use POST for information retrieval when that information corresponds to a potential resource, because that usage prevents safe reusability and the network-effect of having a URI. -- Fielding, 2008

More idiomatic queries would look more like

GET /flights?flight_no=2384B

or even

GET /flights?flight_no=2384B&departure_time=78163918839123&arrival_time=78163918889382

In these cases, nobody would be at all startled that the same "parameters" used in the identifier are also repeated in the representation of the resource.

Given that the query is assigned POST semantics by the client, there's absolutely nothing wrong with a response that looks like:

200 OK
Content-Location: https://example.org/flights?flight_no=2384B&departure_time=78163918839123&arrival_time=78163918889382

In which case having the parameters appear in the response body would also be perfectly normal (just as they would be if the client had used a GET on that resource directly).

are there consequences to ignoring REST principles in situations like these where it is simpler to take shortcuts?

If you relax the REST architectural constraints, then you can no longer expect the corresponding properties to hold.

In particular, when you start replacing the uniform interface with your own bespoke semantics, you sacrifice the capabilities of general-purpose components that could otherwise assist.

Well explained @VoiceofUnreason. In the flight status example, input count is manageable enough to be included as query param. But what if there are too many inputs involved. Is it ok to clutter the URI with say, 10-15 query params? or is it a better design for such a case? — Akshay Singh, Feb 10 '20 at 18:43
number of parameters is not an important constraint. You do need to be careful if the URI itself is long enough that you start running into implementation limits; see https://stackoverflow.com/a/417184/54734 — VoiceOfUnreason, Feb 11 '20 at 12:34

REST : Request as a subset of Response

1 Answers1