79

I have a REST URL to get all users formatted like this: http://example.com/users

To get an individual user by id: http://example.com/users/12345

To get all user's bids: http://example.com/users/12345/bids

To get all user's bids between two dates: http://example.com/users/12345/bids/?start=01/01/2012&end=01/31/2012

or should it be like this: http://example.com/users/12345/bids/start/01012012/end/01312012

I'm leaning towards the 1st date range URL as start and end are not entities in the domain. What is the proper way to format a REST URL with a date range?

Thanks,

Tom

2
  • 10
    I would suggest putting the dates in ISO 8061 format: 2012-01-31. This avoids uncertainty about whether it's month-day-year or day-month-year.
    – Tim Morley
    Mar 8, 2017 at 11:47
  • 1
    If you use the path separator / to delimit the values you're likely to encounter numerous issues. If you decide you want the start and end dates to allow ISO formats e.g. 2021-10-12T01:00:00.000Z, 2021-10-01T18:00:00.000+05:00, those formats contain characters that will break the URL. Much better to use querystring parameters Oct 13, 2021 at 5:39

4 Answers 4

84

http://example.com/users/12345/bids?start=01-01-2012&end=01-31-2012

Have the query parameters on the same "level" as the bids (remove the slash before the question mark). But you would probably want to have support for if they only provide one query parameter. So if they only provided "start" then it would get all bids after that date, or if they only provided "end" it would get all bids before that date.

The reasoning being that query parameters are good for GETting a subset of results from a GET request. They don't go on another level because the next level is usually one specific item with a unique identifier.

2
  • blog posts and senior colleagues I think? I probably shouldn't have been answering StackOverflow questions straight out of college, but I guess it worked out.
    – smcg
    Jun 9, 2021 at 21:10
  • If it's not too much to ask, it might help if you could add some guidelines/documentation or good reads on the topic :)
    – RBz
    Jun 10, 2021 at 14:57
16

I would go with http://example.com/users/12345/bids?start=2012-01-01&end=2012-01-31.

  • There shouldn't be a slash before the query string.
  • Avoid using slashes in the query string. It'll be easier that way.
1
3

If you use the path separator / to delimit the values you're likely to encounter numerous issues. If you decide you want the start and end dates to allow ISO formats e.g. 2021-10-12T01:00:00.000Z, 2021-10-01T18:00:00.000+05:00, those formats contain characters that will break the URL. Much better to use querystring parameters.

I'd recommend using the querystring and ISO format for dates so your URL will look something like this:

https://example.com/users/12345/bids?start=2022-08-08T00:00:00.000Z&end=2022-08-09T00:00:00.000Z

Your API method that retrieves by date range can then be differentiated from the GET request that retrieves all bids for the user, simply by using a different method signature that expects additional start and end date parameters in the request.

1

if example.com/users/12345 gets the user with id 12345, then to get all users by id it should be example.com/users with the id included in the response as a relationship. (usually a hyperlink to that resource).

Now to get them by date ranges it should be example.com/users/start=01-01-2012&end=01-31-2012

The 12345 part is the id of an individual user, it's a resource, therefore it should not be included to get the rest of the users.

As the name of the parameter it should be meaningful. start could mean anything, but start_date is more meaninful.

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