Open Stack

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.

-- 
Chris Dent               (╯°□°)╯︵┻━┻            http://anticdent.org/
freenode: cdent                                         tw: @anticdent