Designing restful APIs path - for returning filtered resource and for returning trimmed properties of a resource

Question

I am not asking the question that is already asked in What is the difference between @PathParam and @QueryParam

This question is related to "best practices" around restful convention.

I have a question resource with the following fields.

 [  
       {  
          "questionId":6,
          "area":"TECHNICAL",
          "title":"Find the index of first 1 in an infinite sorted array of 0s and 1s",
          "description":"Given an infinite sorted array consisting 0s and 1s. The problem is to find the index of first 1 in that array. As the array is infinite, therefore it is guaranteed that number 1 will be present in the array.",
          "state":"ACTIVE",
          "difficultyLevel":"EASY",
          "skills":[  
             {  
                "skillId":1,
                "skillName":"ALGORITHM"
             },
             {  
                "skillId":2,
                "skillName":"PROGRAMMING"
             }
          ],
          "proposedBy":"agrawalo",
          "noOfTimesUsed":0,
          "examples":null,
          "probes":null,
          "approvedBy":null,
          "addedBy":null,
          "dateCreated":"2018-05-16T19:29:11.113",
          "dateLastUpdated":"2018-05-16T19:29:11.113"
       }, 
       {
        ...
       },
       ...
    ]

I exposed a rest controller from my spring application to return all the questions using pathparam "/questions"

Now I want to design Rest URLs for following cases (basically URLs that returns filtered set of questions and urls that return part of a question object). For example:

1. return only titles of all the questions.
2. return only titles of all the technical questions.
3. return questions with skill as algorithm.

I don't think there is a standard convention of doing it. Is there? However, I would like to hear of how people design their REST APIs for use-cases like above. I would also love to hear the reason behind the practice.

Leads here is appreciated.

Answer 1

As you mentioned there is no standard way of doing this.

I would argue that these two are filters:

• return .. of all the technical questions
• return questions with skill as algorithm.

In REST filters are typically realized using query parameters. (Path parameters are used to identify resources. A filter is not a resource, so it is typically not part of the path)

This could look like this:

• /questions?area=technical
• /questions?skill=algorithm

If you require more advanced filters you could have a look into RSQL (for example: https://github.com/jirutka/rsql-parser)

To return only titles of questions one could argue that this can be a seperate title-resouces.

For example:

• /question-titles
• /question-titles?area=technial

If you use custom media types you can also define a reduced media type for this resource and request this type via the Accept-Header: E.g.

GET /questions?area=technial Accept: application/vnd.yourapp.question.short+json

Or you can give the caller more control using an additional query parameter: E.g.:

• /questions?fields=title
• /questions?output=reduced