Open Stack

> -----Original Message-----
> From: Christopher Yeoh [mailto:cbkyeoh at gmail.com]
> Sent: Tuesday, September 23, 2014 7:50 PM
> To: OpenStack Development Mailing List (not for usage questions)
> Subject: Re: [openstack-dev] [all] REST API style guide (Re: [Nova] Some ideas for micro-version implementation)
> 
> On Tue, 23 Sep 2014 09:00:26 +0900
> "Ken'ichi Ohmichi" <ken1ohmichi at gmail.com> wrote:
> >
> > So how about just using HTTP 200(OK) only for status codes?
> > That would give up providing accurate internal status to clients but
> > backwards backwards incompatibilities never happen.
> >
> 
> No I think that we should where possible return the most accurate
> status code. A 202 versus 200 is an important distinction for a user of
> the API (eg do they need to poll for request completion?). How fast
> we can get to accurate status codes through the API is a different
> matter though.

Yes, the most accurate status code is ideal.
My point was:
The most accurate status code depends on the internal implementation.
If we change the implementation which affects resource status like
sync -> async, we should change its status code also with backwards
incompatibility, right?

> > and I have one more idea for making API consistency of whole
> > OpenStack projects. That is each rule of the style guide is
> > implemented in Tempest. Tempest has its own REST clients for many
> > projects and we can customize them for improving qualities. After
> > defining the REST API style guide, we can add each
> > rule to Tempest's base client class and apply it for all REST APIs
> > which are tested
> > by Tempest. We can keep consistent API for the existing projects and
> > apply the style guide to new projects also by this framework.
> 
> That's an interesting idea! However we would have a long exception list
> for a quite a while I think as it was made pretty clear to use we can't
> make a large number of backwards compatible API changes over a short
> period of time. (Like a v2->v3 transition was).

That is a nice point. My idea is that
* The base REST client class contains all style checks with each version
  for using all projects.
* Nova base REST client class inherits from the above class and specifies
  microversions for each style check.

The code would be:

  class BaseRestClient(object):
      version_style_rule_01 = None
      version_style_rule_02 = None
      [..]
      def post(self, url, req_body, version=None ..):
          # Check request body style
          if version_style_rule_01 is None or version > version_style_rule_01:
              self.check_style_rule_01(req_body)
          if version_style_rule_02 is None or version > version_style_rule_02:
              self.check_style_rule_02(req_body)
          [..]
          resp, resp_body = << DO_POST_TO_EACH_PROJECT_API >>

          # Check response body style
          if version_style_rule_01 is None or version > version_style_rule_01:
              self.check_style_rule_01(resp_body)
          if version_style_rule_02 is None or version > version_style_rule_02:
              self.check_style_rule_02(resp_body)
          [..]

  class NovaRestClient(BaseRestClient):
      version_style_rule_01 = 3
      version_style_rule_02 = 4
      [..]

As the default, all style checks are enabled. and in Nova case, we will be able
to specify each microversions as version_style_rule_01/02/...

Thanks
Ken'ichi Ohmichi