Resource modelling in a REST API ( problems with timeseries data& multiple identifiers) [closed]

Question

I have some trouble modeling the resources in a domain to fit with a REST API. The example is obviously contrived and simplified, but it illustrates 2 points where I'm stuck.

I know that:

1. a user has pets
2. a pet has multiple names - one by each member of the family
3. a pet has: a date of birth, a date of death and a type (dog,cat...)
4. I need to be able to query based on dates (actually the date, or range of dates is mandatory when asking about pets). E.g.: tell me what pets I have now; tell me what pets grandma says we had 5 years ago until 3 years ago.

How should I handle dates?

a. in the query string: /pets/dogs/d123?from=10102010&to=10102015 (but as I understand, query string is mostly for optional parameters; and date/range of dates is needed. I was thinking of having the current date as default, if there's nothing in the query string. Any thoughts on this?)

b. somewhere in the path. Before /pets? This seems a bit weird when I change between a date and a range of dates. And my real path is already kind of long

How should I handle multiple names?

The way I see it, I must specify who uses the name I'm searching for.

/pets/dogs/rex -> I want to know about the dog called rex (by whom, me or grandma?). But where to put grandma?

I've seen some people say not to worry about the url, and use hypermedia But the way I understood that(and it's possible I just got it wrong) is that you have to always start from the root (here /pets )and follow the links provided in the response. And then I'm even more stuck(since the date makes for a really really long list of possibilities).

Any help is appreciated. Thanks

Answer 1

What might be useful in such scenarios is a kind of resource query language. It don't know the technology stack that you use, but a JavaScript example can be found here.

1. Absolutely do not put any dates in the path. This is considered as a bad style and users may be confused since, they most of them may be not used to such strange design and simply will not know how to use the API. Passing dates via query string is perfectly fine. You can introduce a default state - which is not a bad idea - but you need to describe the state (e.g. include dates) in the response. You can also return 400 Bad Request status code when dates range is missing in request. Personally, I'd go for default state and dates via query string.

2. In a such situation the only thing that comes to my mind is to reverse the relation, so it would be:

   /users/grandma/dogs/rex
   

   or:

   /dogs/rex/owners/grandma
   

3. What can be done also is to abandon REST rules and introduce new endpoint /dogs/filter which will accept POST request with filter in the body. This way it will be much easier to describe the whole query as well to send it. As I mentioned this is not RESTful approach, however it seems reasonable in this situation. Such filtering can be also modeled with pure REST design - filter will become a resource as well.

Hypermedia seems not the way to go in this particular scenario - and to be honest I don't like hypermedia design very much.