2

Say my application is managing objects called workload, with the following fields. I want to expose a REST interface for user to query workloads by labels.

"Workload": {"id":"test1", "labels":["A", "B", "C"]}
"Workload": {"id":"test2", "labels":["A", "C", "D"]}
"Workload": {"id":"test3", "labels":["A", "B", "D"]}

Question: How do I design the REST endpoint so that it would supports query workload by multiple labels as filter?

Sample Query 1: I want to GET all the workloads with both "A" and "B".

I'm thinking something like GET as verb, workloads as endpoint, then use a {"labels": ["A", "B"]} as request body. But this does not seem like a RESTful way to do things

Alternatively, I can do GET /labels/{label-id}/workloads but this would only work with one label per time.

Sample Query 2: I want to GET all the workloads with label "A" or "B" but no "C"

No clue how to do this sort of rest api at all, other than ask user to query by A, B, C separately then do proper set operations themselves?

The second query is tracked as another question

Community
  • 1
  • 1
cookieisaac
  • 1,357
  • 5
  • 18
  • 35
  • I don't think that there is anything wrong with query parameters. Is there any reason you want to avoid them? – mrmcgreg Sep 23 '16 at 22:22
  • I was having doubt whether I want to/can repeat query parameters. As I am coding my application in `golang`, and I am using a [third party library`httprouter`](https://github.com/julienschmidt/httprouter) to help me automatically parse the parameter, which currently only supports single query parameters... things like `workload/:workload_id/labels/:label_id` – cookieisaac Sep 23 '16 at 23:20

3 Answers3

1

GET verb not takes request body. You should do something like 'workload /labels/A, B, C '. You then get A,B, C in request query. Make an array with comma separated from request query and find records.

Vaibhav Patil
  • 2,603
  • 4
  • 14
  • 22
  • 1. Can I use [comma in URL](http://stackoverflow.com/questions/198606/can-i-use-commas-in-a-url). 2. How to do query like "give me workloads with label 'A' or 'B' but no 'C' " in comma separated list? – cookieisaac Sep 23 '16 at 22:18
  • @cookieisaac Comma in URL depends on server side routing implementation, e.g. by node.js express you can have, by IIS there can be problems. You need to test it first. – inf3rno Sep 23 '16 at 23:39
1

Use query parameters, its fine to repeat them.

GET /workloads?label=A&label=B&label=C

For simple cases you could alsoor and not the terms like this.

GET /workloads?or_label=A&or_label=B&label_not=C
Community
  • 1
  • 1
Graeme Stuart
  • 5,837
  • 2
  • 26
  • 46
  • 1
    This looks good enough for my situation. Just wondering if I can go crazy and do something like `GET /workloads?(label=A||label=B)&label!=C`? Or is there anyway I can do some basic logic operations like '(A or B) not C' – cookieisaac Sep 23 '16 at 22:35
  • You might try posting it as a new question. I can't think of an obvious solution. Perhaps you need another (set of) resource(s) to define your query and then get the results with `GET /queries/{id}/workloads` – Graeme Stuart Sep 23 '16 at 22:41
  • http://stackoverflow.com/questions/10582066/is-that-possible-to-use-in-query-string – Graeme Stuart Sep 23 '16 at 22:45
  • 1
    @cookieisaac There were many previous questions about URI and logical operators, maybe you should check those. e.g. http://stackoverflow.com/questions/25749060/boolean-logic-in-restful-filtering-and-queries – inf3rno Sep 23 '16 at 23:42
0

You have a lot of options the only constraint here, that they should contain A and B. So for example

  • /workloads/?label=["A","B"]
  • /workloads/?label[]=A&label[]=B - aka. query string array
  • /workloads/by/label/A+B/
  • /label/A+B/workloads/

There are existing URI query conventions as well, for example Microsoft Odata. http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part2-url-conventions.html I am not familiar with OData, but according to the docs you should use something like /WorkloadsByLabels(labels=@c)?@c=["A","B"] if you want to follow their approach. Afaik. there is no standard solution to describe complex URI filters.

Community
  • 1
  • 1
inf3rno
  • 24,976
  • 11
  • 115
  • 197
  • It looks like a legit solution, but I've never seen any REST api designed that way...Are these conventional for RESTful endpoints or mostly for URI? I was thinking along the lines like say, [IBM Bluemix REST API](http://ccsapi-doc.mybluemix.net/), but they don't seem to support complex query... – cookieisaac Sep 24 '16 at 00:37
  • @cookieisaac If you are looking for a standard solution, then you should check URI templates https://tools.ietf.org/html/rfc6570 . It defines a list type, which is added to the URI as items separated with comma. Sadly not every server supports comma in URI, e.g. IIS has problems with it. Afaik the plus character is used mostly to separate search keywords and not to separate list items, so it is just a tip, not a convention as far as I know. On the other hand URI templates is a standard, so you can separate the ids with comma if your server supports that. The query string array is standard too. – inf3rno Sep 24 '16 at 03:57