3

I am building a web service following the REST architechture style. I am using JAX-RS to make it easier. This question is however not concerned about a technology, but instead correct use of paths to resources.

I have created some resources in my application such as a Quiz, Question and QuestionFeedback.

I have created paths such as

/quiz /question/1

and so on. Now, I have seen some web service APIs that exposes path such as /approved or /questions/approved. The approved part of the path seems more like attributes that the questions may have (in this case) and I wonder if this is ok, and where the boundry goes between making it a request parameter and a part of the path like this?

And is it ok to expose paths in the web service that in some way exposes one of the intended resources in your system like in this case Question, but through a path like /approved in addition to the normal /questions path? What are the rules, and how is this supposed to be?

If I did not have anyone to ask I would have created a path like /questions?type=approved : GET.

Because approved is not a resource in my system. Or is it ok to create paths that exposes resources...but don't use resource name directly.

LuckyLuke
  • 42,935
  • 77
  • 254
  • 416
  • 2
    Use `/questions?type=approved`. Why not choose the obvious way to go? –  Nov 13 '12 at 14:57
  • 1
    I'd do the same as @Tichodroma suggested. `approved` is a property of `question` so it makes sense. – Alex Nov 13 '12 at 14:58
  • But I want to know when and how to decide this. If what I think is correct. – LuckyLuke Nov 13 '12 at 14:59
  • 1
    /questions/1 is a reference to a specific resource ("Question #1"), so using a path to encode the question's ID makes sense. Callers will expect a GET on this URL to return a resource that represents question 1 itself. /questions?approved=true is a query that filters the list of all questions by those that have been approved. As a caller, I'd expect a GET on this URL to return a list of approved questions. – Greg Brown Nov 13 '12 at 15:07
  • http://stackoverflow.com/questions/11552248/when-to-use-queryparam-vs-pathparam – Blessed Geek Nov 13 '12 at 15:10

1 Answers1

2

You are asking if paths that can only be understood with additional information are OK. Well, they are not wrong but I would not choose them.

Your question is (in my words):

Give me all the questions that have the additional feature of being approved.

This boils down to two steps:

First Step

Get all questions.

GET /questions

Second Step

Of these get only those that have been approved.

GET /questions?approved=true

This is very natural.

In contrast, why should the second step result in /approved? How is this related to /questions? There is no obvious way to answer this question. While it is technically OK to use even strange paths like /pink-elephants which should translate into 'give me all approved questions', it's not what I recommend.

  • That may have been a little odd example. Let say you have a quiz resource `/quiz`. Then you want all the approved questions, then you would have used `/quiz/questions?type=approved` right, and not `/quiz/approved`, even though it is allowed, but it makes a strange looking API? Is that correct? – LuckyLuke Nov 13 '12 at 15:12
  • For this you would have `/quizes/42/questions?type=approved`: Give me all questions for quiz 42 that are approved. Yes, I would recommend this: Questions belong to *one* quiz and they can be approved. –  Nov 13 '12 at 15:14
  • So resources are paths, and attributes they may have is..payload and should not be in the path. – LuckyLuke Nov 13 '12 at 15:25
  • 2
    You don't request *the* attribute but a resources that *has* an attribute. That is a big difference. If you were *only* interested in the *value* of the attribute `type`, you could use `/quizes/42/questions/32/type` to get the `type` attribute of question 23 to quiz 42. But that's not what you want, isn't it? –  Nov 13 '12 at 15:27