Question

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.

Answer 1

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.