Design a rest api with multiple date range

I have a GET rest api and I want to do multiple date range search and that will be passed as query param in the api.

Query param name: start_create_time, end_create_time, start_update_time, end_update_time.

So how should I develop or design the rest api. Below are the 3 different approaches:

1. GET /api/REST/2.0/users/?start_create_time=2019-06-03&end_create_time=2019-06-05 last_update_time=2019-06-06☆t_update_time=2019-06-07

2. GET /api/REST/2.0/users/?start_create_time>2019-06-03&end_create_time<2019-06-05 last_update_time>2019-06-06☆t_update_time<2019-06-07

3. GET /api/REST/2.0/users/?start_create_time={"lt": 2019-06-03, "gt": 2019-06-06} & last_update_time={"lt": 2019-06-06, "gt": 2019-06-07} // pass a json object

I m not sure point 2 and 3 are valid way of designing the api. Can someone please suggest how I can achieve this.

Solved Solved
0 4 9,259
1 ACCEPTED SOLUTION

You have enough data to pass, that it starts feeling unwieldy passing it all as individual query params. So you have begun considering expressing that data in a json-formatted query param.

Some people have resorted to passing json in query params. I personally don't like the idea because it seems like it goes too far. I think the curly braces there makes the whole thing difficult to read and understand. To me, JSON is helpful in a payload, but seems counter-productive in a query param. But It is a matter of taste.

The thing you are trying to design looks like a search request. A GET with a bunch of constraints. I see several reasonable options.

  1. make the search request a POST. This means you can pass a json as the payload of the search. The constraints on the search can expand with your json .
  2. allow the search constraints to be encoded as a single string, and pass that as a single query param. Google for its search interface of course accepts a string that can express specific desires, such as "q=site:example.com bananas allinurl:ripe" You could do something similar eg "q=create:2019-06-01|2019-06-03 update:2019-06-07|2019:06-08" or something like that. The "gt" and "lt" feel unnecessary to me.

If I were doing this i would want the API to accept multiple date formats; with dashes, with slashes, or just seconds-since-epoch.

Also, what about timezones? Is there any thought to include the timezone in the time string? Does it matter?

View solution in original post

4 REPLIES 4

You have enough data to pass, that it starts feeling unwieldy passing it all as individual query params. So you have begun considering expressing that data in a json-formatted query param.

Some people have resorted to passing json in query params. I personally don't like the idea because it seems like it goes too far. I think the curly braces there makes the whole thing difficult to read and understand. To me, JSON is helpful in a payload, but seems counter-productive in a query param. But It is a matter of taste.

The thing you are trying to design looks like a search request. A GET with a bunch of constraints. I see several reasonable options.

  1. make the search request a POST. This means you can pass a json as the payload of the search. The constraints on the search can expand with your json .
  2. allow the search constraints to be encoded as a single string, and pass that as a single query param. Google for its search interface of course accepts a string that can express specific desires, such as "q=site:example.com bananas allinurl:ripe" You could do something similar eg "q=create:2019-06-01|2019-06-03 update:2019-06-07|2019:06-08" or something like that. The "gt" and "lt" feel unnecessary to me.

If I were doing this i would want the API to accept multiple date formats; with dashes, with slashes, or just seconds-since-epoch.

Also, what about timezones? Is there any thought to include the timezone in the time string? Does it matter?

Thanks Dino for the reply, as off now I will accept one date format (2019-06-03T07:50:20.940Z) which is standard for all the apis that we are developing.

In the above api if I want to add a new param as amount which check amount>0,

e.g. . GET /api/REST/2.0/payments/? amount>0 then what is the best way of doing it.

Here again, it sounds like you want a Search API.

Consider implementing a simple query language and passing it as a query param.