Resource modeling in the REST API (problems with temporary data and multiple identifiers)

Question

I have some problems with modeling the resources in the domain to match the REST API. The example is clearly contrived and simplified, but it illustrates 2 points where I am stuck.

I know that:

• the user has pets.
• the pet has several names - one for each member of the family
• The pet has: date of birth, date of death and type (dog, cat ...)
• I need to be able to query based on dates (in fact, a date or date range is required when asking about pets). For example: tell me what animals I have now; tell me what kind of pets grandmothers say we had 5 years ago to 3 years ago.

How do I handle dates?

a. in the query line: / pets / dogs / d123? from = 10102010 & to = 10102015 (but, as I understand it, the query string is mainly for optional parameters, as well as the date / date range. I was thinking about having the current date by default if there is nothing in the query string. Any thoughts on this? )

b. somewhere in the way. To / pets? This seems a little strange when I switch between a date and a date range. And my real path has long been long

How do I handle multiple names?

As I see this, I must indicate who uses the name I'm looking for.

/ pets / dogs / rex → I want to know about a dog called rex (by whom, am I or grandmother?). But where to put the grandmother?

I have seen some people say that you don’t have to worry about the url and use hypermedia. But the way I understood that (and this is possible, I was simply mistaken) is that you should always start from the root (here / pets) and follow the links provided in the answer. And then I get stuck even more (as the date makes a really really long list of possibilities).

Any help is appreciated. Thanks

Answer 1

What may be useful in such scenarios is a kind of resource query language. He does not know the technology stack you are using, but here you can find an example of JavaScript here .

• Absolutely do not put any dates on the way. This is considered a bad style, and users can be confused as most of them cannot be used for such a strange design and simply will not know how to use the API. Passing dates through the query string is excellent. You can enter the default state - this is not a bad idea, but you need to describe the state (for example, include dates) in the response. You can also return a 400 Bad Request status code when the date range is not in the request. Personally, I went by default and dates on the query string.

• In such a situation, the only thing that comes to my mind is to reverse the attitude, so it will:

   /users/grandma/dogs/rex 

  or

   /dogs/rex/owners/grandma 

• You can also abandon the REST rules and introduce a new endpoint /dogs/filter , which will accept a POST request with a filter in the body. Thus, it will be much easier to describe the entire request and send it. As I said, this is not a RESTful approach, however, in this situation it seems reasonable. Such filtering can also be modeled using a clean REST design - the filter will also become a resource.

Hypermedia doesn't seem to be the way to go in this particular scenario - and frankly, I really dislike the design of hypermedia.

Answer 2

You can use the query string if you want, there are no restrictions. The path contains a hierarchical, while the request contains a non-hierarchical part, but this is not necessary.

Upon request, I suggest that you think about the parameters and what will be in the answer. For instance:

I want to know about a dog called rex (by whom, me or grandmother?)

Parameres: rex and grandma , and you need a dog in response.

Thus, the hyperlink will look like GET /pets/dogs/?owner=grandma&name=rex or GET /pets/dogs/owner:grandma/name:rex/ etc. The structure of a URI doesn't really matter if you attach some RDF metadata to the hyperlink and parameters, for example. you can use https://schema.org/AnimalShelter vocab. Ofc. this is not suitable, because it does not apply to several names given by several persons, but it’s nice to start creating your own vocals if you decide to use RDF.