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

Bug #1554869 reported by xiexs on 2016-03-09
6
This bug affects 1 person
Affects Status Importance Assigned to Milestone
neutron
Wishlist
Unassigned

Bug Description

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

Tags: rfe Edit Tag help
tags: added: rfe
summary: - [RFE]Add error codes for HTTP response
+ [RFE] Make API errors conform to API working group schema
Changed in neutron:
status: New → Confirmed
importance: Undecided → Wishlist
xiexs (xiexs) on 2016-03-25
Changed in neutron:
assignee: nobody → xiexs (xiexs)
Changed in neutron:
status: Confirmed → Triaged
status: Triaged → Won't Fix

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.

Changed in neutron:
status: Won't Fix → Incomplete
assignee: xiexs (xiexs) → nobody

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

Changed in neutron:
assignee: nobody → xiexs (xiexs)
status: Incomplete → In Progress
Changed in neutron:
status: In Progress → Triaged
Doug Wiegley (dougwig) wrote :

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

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

Changed in neutron:
status: Triaged → Incomplete
assignee: xiexs (xiexs) → nobody

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

xiexs (xiexs) wrote :

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.

Changed in neutron:
assignee: nobody → xiexs (xiexs)
status: Incomplete → In Progress
Changed in neutron:
status: In Progress → Incomplete
assignee: xiexs (xiexs) → nobody
status: Incomplete → Triaged

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.

Akihiro Motoki (amotoki) wrote :

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) wrote :

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

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

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.

Changed in neutron:
status: Triaged → Won't Fix

Not right now.

xiexs (xiexs) wrote :

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

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.

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.

To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers