2

I am having these web service endpoints:

/quizzes POST - Generates a new quiz on the server and respond with the resource generated.
/quizzes/1/answer/done POST  - Posts an answer to the quiz. Ends the quiz.
/quizzes/1/answer/temporary POST - Posts an answer to the quiz. Pauses the quiz.

I want to be able to toggle the status and the some other fields on the quiz when moving between the different stages.

However, I am not sure what the URI for resuming a paused quiz should be.

And would it be better to separate the task og toggeling the state of the quiz in another request? How should the URI's for that be? I am trying to keep the logic at the server and the interface with the web application as simple as possible.

LuckyLuke
  • 42,935
  • 77
  • 254
  • 416

1 Answers1

3

Remember that for REST you are essentially thinking object oriented.

So you have /quizzes/ To start a new quiz you POST to /quizzes/, that then gives you back the quiz id.

To do a new answer you POST to /quizzes/{id}/answers/. That returns the answer id

To get the status of a quiz you GET from /quizzes/{id} to the answer you GET from /quizzes/{id}/answers/{id}.

To modify the status of the quizz you would PUT to /quizzes/{id}?paused=true, or define a command object in JAXB and/or XML and include that in the body of the PUT request.

Tim B
  • 38,707
  • 15
  • 73
  • 123
  • 1
    `/quizzes/{id}?paused=true` --- it's not RESTful enough. The resource could be `/quizzes/{id}/status`, definitely not a set of arbitrary parameters – zerkms Dec 26 '13 at 09:39
  • That's your opinion. There are no fixed rules for this sort of thing. See http://stackoverflow.com/questions/4024271/rest-api-best-practices-where-to-put-parameters http://www.soapui.org/REST-Testing/understanding-rest-parameters.html http://stackoverflow.com/questions/15947074/extra-query-parameters-in-the-rest-api-url etc. – Tim B Dec 26 '13 at 09:52
  • when it's a defined and a static part of a resource name - it's a common sense to use it like I shown – zerkms Dec 26 '13 at 09:53
  • How is it part of a resource name? The resource is the quizz. Paused is a status of that quizz. – Tim B Dec 26 '13 at 09:54
  • `status` is also a resource – zerkms Dec 26 '13 at 09:54
  • 1
    In your opinion. It's a valid design, it's not the only valid design. – Tim B Dec 26 '13 at 09:55
  • why not use `index?type=quizzes&id=42&paused=true` then? – zerkms Dec 26 '13 at 09:55
  • 1
    For the same reason you don't put all the code for your application in Main(). The goal here is to split things down to the most useful end size. In my opinion "status" is too small to warrant existing as its own object, the fundamental objects here are quizz and answer. Almost certainly the status value is a single field in the quizz object. Unless there is going to be a lot of different operations on that status or a lot of cause to query it independently, etc then it is pointless to break it out as its own separately addressable object. – Tim B Dec 26 '13 at 09:58
  • But of course that's a decision that may change depending on how it is being used. As I already said your approach is valid too. Both approaches are valid and which is best would depend on how it is being used. Personally I prefer to start simple (i.e. only the objects I know I need) and expand out if required. – Tim B Dec 26 '13 at 09:59
  • "and implementation guidelines" --- I actually cannot remember any reputable book or article that recommended to use named parameters for anything but filter-alike features. If you want to modify the state of the object why don't you use `PUT /quizzes/{id}` and send `paused=true`? If you're modifying the `/quizzes/{id}` resource - you should `PUT` to it. If you modify the `status` resource - why don't you accept `/quizzes/{id}/status` as a more correct name? – zerkms Dec 26 '13 at 10:04
  • That would work too, in fact that was one of my suggestions (although I suggested using a json or xml command object). This discussion is going on way too long though so I'm leaving it here. :) – Tim B Dec 26 '13 at 10:06
  • "in fact that was one of my suggestions" --- it's weird, but I don't see it :-S "This discussion is going on way too long though so I'm leaving it here" --- yep, following something consistently is difficult indeed :-) – zerkms Dec 26 '13 at 10:09
  • @zerkms: actually, when you use form encoding the request is sent using query parameters... – Marjan Venema Dec 26 '13 at 19:39
  • @Marjan Venema: not sure what "form encoding" term from the HTTP perspective means (it doesn't even introduce a "form" term, does it?), but `PUT` can have a request body, and I don't see a good reason to not use it. – zerkms Dec 26 '13 at 20:53
  • When you submit a form with a Web browser you can choose to submit the form as get or post. A get submit encodes the form values in the URL. I think that is what is meant. – Tim B Dec 26 '13 at 21:17
  • @zerkms: The term is probably url-form-encoding but that was not the point. Whether a request can have a body is irrelevant to the question of whether something is RESTful or not. Whether you send form values in a request body or as query parameters in the URL doesn't make the request any more or any less RESTful. The RESTfulness of an API stems from the fact that you identify resources and use a limited number of verbs on them. The rest (sic) are implementation details. – Marjan Venema Dec 27 '13 at 15:50