This question relates to a somewhat more specific case than the one discussed in How can I create a RESTful calculator?
It should be assumed that the values to be calculated are not simple integers, but large and complex puzzles. Such a puzzle can also contain several subpuzzles. Both can be stored/read as resources on/from a server, like:
GET /myApi/puzzle/{puzzleID}
GET /myApi/puzzle/{puzzleID}/subpuzzle/{subpuzzleID}
Afterwards, clients can trigger a calculation of them on the server. As in the above link, the resources would be located in the body of a POST request. Instead of getting and sending the puzzles, i want to refer to the already existing ones on the server. My current solution is to reference them via their URI.
This request triggers a calculation of the puzzle (and all contained subpuzzles) with ID=123:
Request:
POST /myApi/puzzleSolver
Content-Type: text/plain
/myApi/puzzle/123
This request triggers just a calculation of the subpuzzle with ID=321 in the aforementioned puzzle:
Request:
POST /myApi/puzzleSolver
Content-Type: text/plain
/myApi/puzzle/123/subpuzzle/321
Is it advisable to directly specify the resource URI in the request body - am I missing any pitfalls? Is there a better alternative, e.g. to use the puzzleID
and subpuzzleID
?
/myApi/puzzleSolver
? Why don't you just request the result of the puzzle itself, something like/myApi/puzzle/123/result
It seems like apuzzleSolver
resource is completely unnecessary? Unless I'm missing something/myApi/puzzle/123/result
and/myApi/puzzle/123/subpuzzle/321/result
). I could also think of even more deeply nested scenarios, e.g. a calculator for the electricity consumption of countries, communities, villages and individual houses. It is definitely also a possibility, but due to the hierarchical structure, I prefer the approach with thepuzzleSolver
.puzzleSolver
design that resource doesn't have a URL and is undiscoverable (ie you can't link or navigate to it). You POST to another faux-resource to get the resource you actually want. URLs are unique resource locators, your resources should all have their own URL that uniquely identifies them and only them. A God resource that can return lots of different resources is a REST anti-pattern. Anyway my 2 cents, if you don't like it you don't like itGET
is inappropriate. First, the calculation should be triggered through aPOST
request, but the URL/myApi/puzzle/123/result
feels wrong for that?! Despite, the URL can serve for a finalGET
request to get the result, as soon as the task is completed. That is my current (non-expert) view on this.Retry-After
header that gives an estimate of when the server will be ready. Ultimately the client shouldn't care about any work the server is doing to produce the resource. It just cares about the resource. If it can't get it right now it only cares about when it can get it. REST is designed to de-couple client from server implementation