[RFE] Make API errors conform to API working group schema

[xiexs]

Error codes with more detailed information about the errors will
be quite useful for the developers when using an neutron API.

Thus we should add a wrapper to collect the error codes and rearrange them
with a appropriate design pattern [1] while the REST API has encountered some errors,
and then return the request users.

[1] http://specs.openstack.org/openstack/api-wg/guidelines/errors.html

[Armando Migliaccio (armando-migliaccio)]

This is a catch-all bug that's too broad to deal with. Besides, that implies changing the current API? Please provide a specific and targeted example.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/298704

[Doug Wiegley (dougwig)]

I have the same question as armax: are these api error changes additive, or will we be breaking backwards compat to switch?

[Armando Migliaccio (armando-migliaccio)]

Status update:

http://eavesdrop.openstack.org/meetings/neutron_drivers/2016/neutron_drivers.2016-03-31-22.00.log.html#l-262

[Armando Migliaccio (armando-migliaccio)]

Time is not ripe for such a change especially if it means not preserving backward compatibility.

[Armando Migliaccio (armando-migliaccio)]

@xiexs: please provide input on how you intend to preserve sanity of existing API

[xiexs (xiexs)]

Hi, Armando & Doug & Ihar,
Thanks a lot for your review.

>are these api error changes additive, or will we be breaking backwards compatibility to switch?
Actually I have ever considered the former pattern which described by the patch set 1 (#298704). In this pattern, the old message and the new message will be output together.

But according to your tips, I think the later one will be a better idea.
Then the following solution will be proposed to preserve the backwards compatibility:

We will suppose a new field, named as 'Neutron-Common-Error-Format' temporarily , in the HTTP header that is sent to the neutron APIs.
And then based on whether the field is specified or not, or which value is set to the option, we can maintain the backwards compatibility, i.e.:
 - Keep the old error format if that field is not specified or set to False.
   Which means there is not any changes to the existing error message, and in this case the users and the existing APPs won't feel any changes at all.
   By default, neutron APIs will work with this pattern.

 - Return the new error format while that field is specified and meanwhile is set to True.
   In this case, the option must be explicitly set to True and it will break the backwards compatibility.

Does it make sense to you?
Or I will really appreciate if you guys tell me a better idea, thanks in advance.

[Armando Migliaccio (armando-migliaccio)]

The idea of influencing Server behavior through a header is the most promising though it feels like a poor-man attempt to do micro-versioning. We'd definitely need to expose this capability through an extension in order to advertise the client that the header specification will be honored.

[OpenStack Infra (hudson-openstack)]

Related fix proposed to branch: master
Review: https://review.openstack.org/302127

[Akihiro Motoki (amotoki)]

General idea itself looks good. The idea of using a header to indicate which format is expected looks a good option.

I would like to comment some points if we go to this way.

* As Armando commented, in the current neutron API, the extension list is the only way to expose capabilities supported by neutron-server, so we need to add an extension corresponding to this feature.
* It is better to discuss with API-WG about the header name: Neutron-* or OpenStack-* or Networking-*. The proposal is specific to Neutron, but the same approach may be used for other projects which do not adopt micro-versioning yet.
* If we use the header, the default mode should be legacy when the header is not specified.
* neutronclient implementation should be done along with the server side implementation

[xiexs (xiexs)]

Thanks for your review and advice.
Your comments all are included in the spec [1], could you please also help me review it? Thanks in advance.

BTW, as the [2] mentioned, some folks think the microversion would be the best choice for this feature.
But IMO, it will take a long time to introduce the microverion into neutron, so during the interim period,
we can keep going on the improvement about the error message format.
What do you think?

[1] https://review.openstack.org/#/c/298704/
[2] http://lists.openstack.org/pipermail/openstack-dev/2016-April/091949.html

[Armando Migliaccio (armando-migliaccio)]

Let's discuss this again. The aspect to take into account is priority over other API related efforts.

[Armando Migliaccio (armando-migliaccio)]

Status update:

http://eavesdrop.openstack.org/meetings/neutron_drivers/2016/neutron_drivers.2016-04-14-22.00.log.html#l-182

[Armando Migliaccio (armando-migliaccio)]

It seems that there is reluctance to bless the effort on top of the existing API framework. People feel like it'd be better if this were tackled in the context of an API overhaul, so we'll have to reject it for now.

[Armando Migliaccio (armando-migliaccio)]

Not right now.

[xiexs (xiexs)]

Thanks for your discussion about this feature.
OK, we will suspend this work until the microversion feature was landed into neutron.

[OpenStack Infra (hudson-openstack)]

Change abandoned by Armando Migliaccio (<email address hidden>) on branch: master
Review: https://review.openstack.org/298704
Reason: This review is > 4 weeks without comment and currently blocked by a core reviewer with a -2. We are abandoning this for now. Feel free to reactivate the review by pressing the restore button and contacting the reviewer with the -2 on this review to ensure you address their concerns.

[OpenStack Infra (hudson-openstack)]

Change abandoned by Armando Migliaccio (<email address hidden>) on branch: master
Review: https://review.openstack.org/302127
Reason: This review is > 4 weeks without comment, and failed Jenkins the last time it was checked. We are abandoning this for now. Feel free to reactivate the review by pressing the restore button and leaving a 'recheck' comment to get fresh test results.