openstack team mailing list archive

[Joseph Heck <heckj@xxxxxxx>]

First a thank you to everyone who's swung by to read (and some comment) on the V3 draft at https://docs.google.com/document/d/1s9C4EMxIZ55kZr62CKEC9ip7He_Q4_g1KRfSk9hY-Sg/edit?pli=1. It's been immensely useful.

To clear up a bit of confusion I caused (sorry Jay!) - there were *no* example responses included in the document, although some of the pieces certainly looked like they might be. I put in placeholders for example responses to be added to make it more explicit, and cleaned up my formatting so that I was consistent (and hopefully through that, more clear)

This morning/afternoon I went through and tried to provide answers and feedback to most of the outstanding comments - the folks who commented will see the results through the Google doc responses as they have notifications defined. I made a few changes to the draft - in particular, identifing what the "primary key" in the resource attributes would/should be from a REST perspective, and crossing out or adding a few attributes here and there based on feedback. I also tried to make some spelling fixes where I missed earlier.

I've also added an open points discussion near the top of the document, and I'd like to raise a few of those issues here on the mailing list.

First - what's the current thought of support for PATCH vs PUT in updating REST resources? Are there any issues with clients being able to use a PATCH verb? It's not something I'm super familiar with, so I'm looking for feedback from the community here. Ideally, I'd like to support the semantics of the PATCH HTTP verb, and possibly just assert no support for the PUT verb to be clear about intended functionality. Is that going to throw anyone for a loop?

Second - filtering/searching for resources. The draft includes a section labelled "Query By Name", which is probably mis-labelled, as it's intended to cover the general idea of passing in query parameters to general listing resource endpoints to filter the result set. The API endpoints across all the resources are defined as plurals, with the idea that specificity comes later in the URI (for referencing a single resource), or that we could add on these query parameters to restrict/filter by resource type. 

Would it be better to make each of the query parameters explicit in the API beyond the pagination?

Third - there's a general workflow question about how to go from "username + password" to a token scoped to a specific tenant. There are a few suggestions outstanding:

1) make a default tenant concept on a user, and when the user authenticates and gets a token, it's initially scoped to that specific tenant *unless* the authentication request also explicitly passed in an alternative tenant_id. 

	1a) The user could then look up any additional tenant_id from the /users/{userid}/tenants resource path.

	1b) a variation of this could be to include a list of all tenants the user is associated with in the token resource when it's returned, with the token scoped by default to whatever is set in the user's "default tenant" attribute.

2) when any authentication that is just handed in a username+password and no tenent_id, hand back a list of tokens, all authenticated for the user.

Fourth - there's an outstanding suggestion that the token resource, in particular, may be much better suited to including whole resources back, instead of resource IDs or atom link references to those resources. That's generally how /token is behaving in the v2 API, and I'm leaning towards making that explicit in the V3 API as well. Right now the APi defines only that the ID's will be returned, not representations of the whole resource. 

Thoughts? Feedback?

-joe