1

How should a query look like when I want to retrieve last measurements from installations that aren't removed?

Something like that?

/my-web-service/installations/measurements/last?removed=false

The thing is, I don't want to retrieve last measurements that weren't removed from installations. I want to retrieve last measurements from installations that weren't removed.

Opal
  • 81,889
  • 28
  • 189
  • 210
Defozo
  • 2,946
  • 6
  • 32
  • 51

2 Answers2

1

According to this best practices article, you could use "aliases for common queries":

To make the API experience more pleasant for the average consumer, consider packaging up sets of conditions into easily accessible RESTful paths. For example, the recently closed tickets query above could be packaged up as GET /tickets/recently_closed

So, in your case, it could be: 

/my-web-service/installations/non_removed/measurements/last

where non_removed would be an alias for querying installations that weren't removed.

Hope it helps!

Héctor
  • 24,444
  • 35
  • 132
  • 243
1

I see a couple possibilities here:

  1. If you need to read the data from the endpoint transactionally, the way you designed it is the way to go. What I'd change is the name of the param from removed to installationRemoved since it's more descriptive and shorten the endpoint to /my-web-service/measurements/ - since with installations it's unclear in which scope does the client operate. Also, don't you need since param to filter the last measurements?

  2. It there's a chance to split the two endpoints I'd add:

    • /my-web-service/installations/?removed=false
    • /my-web-service/measurements/?since=timestamp&installations=<array>

    It does not make it better (when it comes to better or worse) but easier and more predictive for the users.

In general try to add more general endpoints with filtering options rather then highly dedicated - doing one particular thing. This way leads to hard to use, loose API. Also, on filtering.

And final notice, your API is good if your clients use it not because they have to but when they like it ;)

Opal
  • 81,889
  • 28
  • 189
  • 210
  • At first, shouldn't it be `measurements?since=` rather than `measurements/?since=`? And the second thing is, should I have an array in my url in the form of `&installations=[1, 2, 3]` or `&installation=1&installation=2&installation=3`? – Defozo Nov 14 '17 at 14:19
  • @Defozo, it should definitely end with slash, always ;) When it comes to the latter, it depends on your technology stack (not being very demanding to implement), and well known standards - so it seems that it should be: `installation=1&installation=2&installation=3` when it comes to how arrays are handled in HTTP query params. – Opal Nov 14 '17 at 14:23
  • @Defozo, it's up to you ;) I always end the endpoints with slash. – Opal Nov 14 '17 at 14:38
  • I deleted my comment because I found your answer here: https://stackoverflow.com/questions/5020704/how-to-design-restful-search-filtering where you doesn't use slash at the end and thought that you just kidding me here :D – Defozo Nov 14 '17 at 14:40