[openstack-dev] [api] service type vs. project name for use in headers

michael mccune msm at redhat.com
Thu Jan 28 14:50:22 UTC 2016

On 01/28/2016 06:32 AM, Jay Pipes wrote:
> Couldn't agree more, Chris.
> -jay
> On 01/28/2016 11:06 AM, Chris Dent wrote:
>> On Wed, 27 Jan 2016, Dean Troyer wrote:
>>> I think we would be better served in selecting these things thinking
>>> about
>>> the API consumers first.  We already have  enough for them to wade
>>> through,
>>> the API-WG is making great gains in herding those particular cats, I
>>> would
>>> hate to see giving back some of that here.
>> I think it is high time we resolve the question of whether the
>> api-wg guidelines are evaluating existing behaviors in OpenStack and
>> blessing the best or providing aspirational guidelines of practices
>> which are considered best at a more universal level.
>> Within the group many of our debates pivot around the above issue.
>> There is some fear that if we choose the latter none of the
>> guidelines will be followed.
>> I think that's pretty weak sauce and we need to take both a more
>> assertive and more aggressive stance with regard to achieving
>> quality and consistency in the APIs[1]. Reaching consistency is the
>> primary mission of the group but consistent crap is still crap and
>> our API consumers deserve better.
>> The thread about Ekko which has spawned a subthread about the
>> collision between the ceilometer and monasca APIs should be a
>> good learning moment™: Having some rigor and vision in our
>> guidelines would allow us to state things like:
>> * The APIs are services (for which there could potentially be other
>>    implementations but the service represents a namespace)
>> * Identifiers used in that service are service related, not project
>>    related.
>> * More specifically: URIs are signifiers of a service, not a project.
>> The guidelines should be one (of several) ways in which a project
>> can ask itself "are we being OpenStack?". If there is a collision
>> with the guidelines, that provides a clue that the thing being
>> considered is out of alignment. It should be an excuse to change or
>> create new guidelines.
>>> In this case, the use of service type as the primary identifier for
>>> endpoints and API services is well established, and is how the service
>>> catalog has and will always work.
>> For the specific issue of the headers, I think the above is the crux of
>> the biscuit. The service catalog is intended to be a source of truth;
>> that truth should be reflected in the guidelines. If the API being
>> considered isn't (planned to be) in the service catalog does that
>> API need to even be thinking about adhering to OpenStack guidelines?
>> [1] Choosing to be more rigorous in the guidelines puts a large
>> burden on the group to not simply rubberstamp incoming guidelines
>> and also be more selective about what actually matters in terms of
>> the guidelines. This is challenging because it became clear early on
>> that adherence to correct HTTP in existing APIs was weak and there
>> was an opportunity for the group to be a fount of knowledge and
>> wisdom and distill best practices.
>> That work still needs to go on, but it is also time to align
>> the work with some of the main themes in today's OpenStack:
>> * alignment with the service catalog and what it is trying to
>>    accomplish
>> * effective use of APIs when re-using real users' client code amongst a
>>    diversity of clouds
>> Just those two things can help us evaluate proposals with some
>> useful constraints.

i agree as well Chris, and well said.

thanks to everyone for commenting on this issue. i agree with the 
sentiments that are being voiced here, and i think the arguments for 
sticking to service type make a good deal of sense.

my main concern was that there had been some pushback on the idea of 
service type for headers. i like the notion that we are hewing closer to 
the service catalog ideals, that makes good sense to me. i just wanted 
to leave room for projects to make their own path if necessary, i guess 
this option is always there by default.

again, thanks for the insights. i will back off my concerns on the 
outstanding reviews based on this issue, and work towards helping us 
stay closer to service type for the guidelines.


More information about the OpenStack-dev mailing list