On Thu, 2012-06-21 at 10:27 +0100, Salvatore Orlando wrote:
> > > We could do a query that specified filter network_id=ABC, but it was
> > > already a bit wonky to do something like fixed_ips=10.0.0.2 because
> > > fixed_ip was really a list, not a string. Were you envisioning a
> > > model where a filter on a list was implicitly converted to a ORed
> > > comparison against each list item?
> >
> > I would compare it to the 'in' test in python. And I'm going to go back
> > on my previous email and say it should be:
> >
> > GET /ports?fixed_ip=10.0.0.2
> >
> > To be explicit that you are searching for match of an element in the
> > collection.
>
> How does your example explicit that we are searching for a match of an
> element in a collection?
fixed_ips is the collection, fixed_ip is the element in the collection.
I think by using the pluralized form it makes sense to know that this is
a collection and the non-pluralized that its an element in the
pluralized collection.
So to take it further:
GET /ports?fixed_ips=10.0.0.2&fixed_ips=172.16.0.1
*Could* translate to:
WHERE ['10.0.0.2', '172.16.0.1'] == fixed_ips
And
GET /ports?fixed_ip=10.0.0.2
would translate to:
WHERE '10.0.0.2' IN fixed_ips
Note however I'm -1 on allowing the search of the exact collection, I
think it would make it confusing, but this is an implementation detail
left to plugin vendors.
> This kind of reminds me of the problem we had in API v1 filters when
> searching for ports in networks.
> We just did: GET v1.1/networks?port=<port_uuid> which is probably not
> quite right as I understand Dan's comment on fixed_ip not being really
> a scalar but a list.
>
> What if we prepended "has_" to query parameter looking for elements in
> collections (or second-level resources)?
Yea I'm indifferent on just creating a DSL for querying.
> >
> > > If thats the case, then the same trick could still be used, if we have
> > > a way of referring to nested keys. One option would be to do
> > > something like:
> > >
> > >
> > > { 'id' : XYZ,
> > > 'network_id': "ABC"
> > > 'fixed_ips': [ { "address": "10.0.0.2", "subnet_id": "DEF"} ]
> > > }
> > >
> > >
> > > and allow filters like fixed_ips.address=10.0.0.2 . Essentially,
> > > nested keys are joined by some delimiter, like ".".
> >
> > Right, we'd have to invent and document a "SQL over HTTP" system for
> > filtering inside a collection of resources.
>
> Is this a different kind of problem, like fixed_ip not only being a
> list, but being a structured entity too?
Right, its an object (and really a resource) all in its own then that
has its own set of attributes.
> > > Another option would be to just define a filter key that does not
> > > directly map to a top-level attribute (e.g.
> > > fixed_ip_address=10.0.0.2).
> >
> > We could, I'm +/-0 on just inventing our own query semantics just so we
> > can get something working. My original goal was to have it as straight
> > forward as possible for the API consumer. "I want to filter for a
> > fixed_ip, so that's what I'd pass in". Not "I want to filter for
> > fixed_ip, let me look up in the document what the semantics are for
> > reaching into that collection of resources, ok in this case its
> > fixed_ip_address".
> >
>
> Agreed. We should aim at having an API so simple the user does not
> even have to read the docs to start using it.
>
> > > On the plus side, I think the idea of passing in the subnet-id handles
> > > the other issue you mentioned previously, in that it gives us a clean
> > > way to add an IP to a port even if the user wants that IP to be
> > > allocated from a pool, since the user can add an entry to the fixed
> > > ips list, but only specify the subnet.
> > >
> > >
> > > any other ideas on this front?
> >
> > POST /ips?subnet_id=<UUID>&port_id=<UUID>
> >
> > For allocate out of the pool and
> >
> > POST /ips?subnet_id<UUID>&port_id=<UUID>&address=10.0.0.3
> >
> > For a specific address. (swap out the query string for a body if it
> > seems particularly nasty, but either should be supported in my opinion)
> >
>
> Why does this seem nasty to you?
It doesn't. Its just whether its the query string, a form-encoded body,
or a json body of the same format, it really doesn't matter all that
much, so I was pointing out that I see them all as interchangeable. My
personal preference however is the query string or the form-encoded
body, as a POST with a json body to me seems like a request with a
partial resource. In this case it is since the selectors end up being
part of the resource object, but in other api's I've used that's not
always the case, so I err on that side.
Happy Hacking!
7-11
--
Mailing list: https://launchpad.net/~netstack
Post to : netstack@lists.launchpad.net
Unsubscribe : https://launchpad.net/~netstack
More help : https://help.launchpad.net/ListHelp
