Open Stack

> -----Original Message-----
> From: Christopher Yeoh [mailto:cbkyeoh at gmail.com]
> Sent: Wednesday, February 26, 2014 11:33 AM
> To: openstack-dev at lists.openstack.org
> Subject: Re: [openstack-dev] [nova] Future of the Nova API
> 
> On Tue, 25 Feb 2014 09:26:09 -0500
> Sean Dague <sean at dague.net> wrote:
> >
> > What I want out of Nova API at the end of the day:
> >
> > 1. a way to discover what the API is
> >
> > because this massively simplifies writing clients, SDKs, tests, and
> > documentation. All those pipelines are terribly manual, and have
> > errors in them because of it. Like has been said before you actually
> > need to read the Nova source code to figure out how to use parts of
> > the API.
> >
> > I think this is a great example of that -
> >
> https://blog.heroku.com/archives/2014/1/8/json_schema_for_heroku_platform_api?utm_source=newsletter&utm_medium=email
> &utm_campaign=januarynewsletter&mkt_tok=3RkMMJWWfF9wsRonuKzNZKXonjHpfsX57OQtX6SxlMI%2F0ER3fOvrPUfGjI4AScJrI%2BSLDwEY
> GJlv6SgFQrjAMapmyLgLUhE%3D
> >
> 
> So from what I understand I think the jsonschema work that Ken'ichi has
> been working on for V3 goes a fair way in being able to support this
> sort of thing.

Yes, right.
On the sample Sean pointed, the API reference documentation is being
maintained with using jsonschema. That is the best situation I hope for
Nova API documentation. We will be able to generate/get complete API
documentation with synchronizing the API implementation in this situation.

As the first step, I've proposed the API sample generator[1] which auto-
generates API sample files from API schema. I created a prototype[2], and
I've confirmed it is not so difficult to implement it.


> The jsonschema we'd be able to provide for V2 however is a bit trickier
> as we'd have to leave the input validation pretty loose (and probably in
> rather wierdly inconsistent ways because that's how its implemented) in
> most cases.

Right. If applying strict jsonschema validation to v2 API, the backward
incompatibility issues would happen. so we have to apply loose validation
to v2 API if we need it, but I am not sure that such v2 API validation is
worth.


> > = Current tensions =
> >
> > Cloud providers want v2 "for a long time" (which, honestly, was news).
> > I'm not sure I completely know what that means. Are we talking about
> > the bug for bug surface that is today? Are we talking about not
> > wanting to change endpoints?
> 
> So the problem here is what we consider a "bug" becomes a feature from
> a user of the API point of view. Eg they really shouldn't be passing
> some data in a request, but its ignored and doesn't cause any issues
> and the request ends up doing what they expect.

In addition, current v2 API behavior is not consistent when receiving
unexpected API parameters. Most v2 APIs ignore unexpected API parameters,
but some v2 APIs return a BadRequest response. For example, "update host"
API does it in this case by https://github.com/openstack/nova/blob/master/nova/api/openstack/compute/contrib/hosts.py#L185

Through v3 API development, we are making all v3 APIs return a BadRequest
in this case. I think we cannot apply this kind of strict validation to
running v2 API.


Thanks
ken'ichi Ohmichi

---
[1]: http://lists.openstack.org/pipermail/openstack-dev/2014-February/026537.html
[2]: https://review.openstack.org/#/c/71465/