3

I am designing a REST API for inserting a record to the "solutions" table. A "solution" has a solverID, problemID. I have two different designs in mind:

POST /solutions

and passing the solverID and problemID in JSON with the content of the solution. Or putting the solverID and problemID in the URI:

POST /users/:solver_id/problems/:problem_id/solutions 

Which design is better?

3 Answers 3

1

It's a good practice to define your resources in a consistent hierarchy, so that they are easily understandable and predictable.

Let's say this is the URL to retrieve a question -

GET     /users/{solverId}/problems/{problemId}

It clearly conveys that the problem belongs to the {solverId}.

The following URL would clearly show that the we are retrieving all solutions for problems solved by {solverId}

GET     /users/{solverId}/problems/{problemId}/solutions

To create a new solution for the {problemId}, you would do a post on

POST     /users/{solverId}/problems/{problemId}/solutions

To retrieve a particular solution you would do a get on

GET     /users/{solverId}/problems/{problemId}/solutions/{solutionId}

When to use Ids in path vs query ?

If an ID is definitely required to identify a resource, use it in the path. In the above scenario, since all three Ids are required to uniquely identify a solution, all of them should be in the path.

Let's say you want to retrieve a solution that was given in a particular date range, you would use the following

GET     /users/{solverId}/problems/{problemId}/solutions?startDate={}&endDate={}

Here startDate and endDate cannot uniquely identify a resource, they are just parameters that are being used to filter the results.

4
  • Thanks. The criteria to decide using ids in path vs query seem to be a good one. However, in my case, a user could never get other users' resources. So the {solverId} is always the current user's Id, otherwise the server will reject it. In such case, is it necessary to put a {solverId} in the path? Mar 24, 2013 at 17:44
  • Also, if the {solutionId} is globally unique, wouldn't it be better to use GET /solutions/{solutionId} to get a solution? Mar 24, 2013 at 17:45
  • For the first question regarding {solverId} - REST services are supposed to be stateless, so the service wouldn't know what the current user's id is. So, you'll have to somehow convey it to the service. Putting {solverId} it in the path is one way of conveying it.
    – Sashi
    Mar 25, 2013 at 14:15
  • Regarding {solutionId} - Yes, if the {solutionId} is unique, you could go with 'solutions/{solutionId}' as the path. But, if you want your URLs to convey a meaningful hierarchy where users will be able to guess what a URL exactly means, you could go with "/users/{solverId}/problems/{problemId}/solutions/{solutionId}". This longer URL conveys that the solution they are looking at is for a problem with {problemId}. They could now easily look at the problem by using the URL "/users/{solverId}/problems/{problemId}". I think there is no hard and fast rule on what approach you use.
    – Sashi
    Mar 25, 2013 at 14:21
1

Go with the first one. I would keep your urls as clean and simple as you can. Here are some other examples off the top my head. Not sure on your entire structure.

POST /solutions

GET /solutions?solverid=123  //query solutions by user

GET /users/555/problems      // problems for a given user
GET /users/555/solutions     // solutions for a given user

GET /problems/987/solutions  // solutions for a given problem
2
  • I am actually not clear when an ID should be in the route, when it should be in the query string/request body. For example, why not: GET /problems/987 and GET /problems?user_id=555? Mar 15, 2013 at 3:02
  • Good point. I work with a framework that accepts both. If its the primary key or unique I will use it in the path. If its more like a search to query then I will put it in the query string.
    – kampsj
    Mar 15, 2013 at 11:57
0

I came up with a scheme: including user ID in the route only when authentication is not needed for the route, otherwise, the user ID can be figured out from the authentication information, and the above route becomes:

POST /problems/:problem_id/solutions

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.