Misdescription of a response code for "Create floating IP" in Neutron API Reference

[watanabe.isao]

The response code for the following Neutron API is described as 200 in
http://developer.openstack.org/api-ref-networking-v2.html.
POST /v2.0/floatingips

But the response code should be 201 because this API is creating new floating ip.
Additionaly, the response code is implemented as 201, so this bug is simply misdescription in the API Reference.

[OpenStack Infra (hudson-openstack)]

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

[Anne Gentle (annegentle)]

How do you know the code is right? I'd like an additional person to confirm the original intent.

[watanabe.isao (watanabe.isao)]

Hello, Anne Gentle (annegentle).
Could you help me to confirm about this issue, please?
Here is my confirmation procedure. Please FYI.

===command===
$ neutron net-create hogehoge --router:external True
Created a new network:
+---------------------------+--------------------------------------+
| Field | Value |
+---------------------------+--------------------------------------+
| admin_state_up | True |
| id | d9eb9f00-dc2c-4fbf-89e9-70a79641e91d |
| name | hogehoge |
| provider:network_type | vxlan |
| provider:physical_network | |
| provider:segmentation_id | 1002 |
| router:external | True |
| shared | False |
| status | ACTIVE |
| subnets | |
| tenant_id | e8ca6431d808494a839de2f18a26f10c |
+---------------------------+--------------------------------------+

$ neutron subnet-create hogehoge 192.168.1.0/24
Created a new subnet:
+-------------------+--------------------------------------------------+
| Field | Value |
+-------------------+--------------------------------------------------+
| allocation_pools | {"start": "192.168.1.2", "end": "192.168.1.254"} |
| cidr | 192.168.1.0/24 |
| dns_nameservers | |
| enable_dhcp | True |
| gateway_ip | 192.168.1.1 |
| host_routes | |
| id | be1d5068-ded7-4cbd-92d6-126a1bd771a8 |
| ip_version | 4 |
| ipv6_address_mode | |
| ipv6_ra_mode | |
| name | |
| network_id | d9eb9f00-dc2c-4fbf-89e9-70a79641e91d |
| tenant_id | e8ca6431d808494a839de2f18a26f10c |
+-------------------+--------------------------------------------------+

$ neutron floatingip-create hogehoge
Created a new floatingip:
+---------------------+--------------------------------------+
| Field | Value |
+---------------------+--------------------------------------+
| fixed_ip_address | |
| floating_ip_address | 192.168.1.2 |
| floating_network_id | d9eb9f00-dc2c-4fbf-89e9-70a79641e91d |
| id | 446da1ad-04f0-4fad-ab0a-c39667763c7c |
| port_id | |
| router_id | ...

[watanabe.isao (watanabe.isao)]

Add one thing:
The "trace log" in comment #3 is from /opt/stack/logs/screen-q-svc.log

[Anne Gentle (annegentle)]

Your method still just indicates an opinion that 200 means success and 201 means created, which yes are classics, but if you look at the bulk create floating IPs for compute API at http://developer.openstack.org/api-ref-compute-v2-ext.html#ext-os-floating-ips-bulk it is a 200 that's returned.

Do you have a way to look through the git code to ensure this response didn't change at some point in neutron? How do we know that users don't expect a 200?

The API Working Group is working through inconsistencies like this. I'd like to bring this up there.

[Anne Gentle (annegentle)]

Hi Salvatore, since you've been part of the API definition for neutron, can you say whether 201 or 200 is the original intent for creating a floating IP? I can't trace through the code well enough to know whether the code changed or the spec changed. Thanks!
Anne

[Anne Gentle (annegentle)]

One more related historical doc is http://docs.openstack.org/api/openstack-network/2.0/content/floatingip_create.html -- shows a 200. Did the code originally implement 200 and get changed to 201?

[watanabe.isao (watanabe.isao)]

Hello, Anne Gentle.
Seems like someone changed the neutron code, but forgot to change the API referrence and Admin Guide.
The neutron code is: https://github.com/openstack/neutron/blob/master/neutron/api/v2/resource.py
line 49
as you can see, all create response codes in neutron are 201.
This line has not been changed in the last 10 fixes, since Dec 4, 2013 (checked from histroy).

[watanabe.isao (watanabe.isao)]

I'm sorry.
Seams like someone forgot to change the document since the very first of neutron.
https://github.com/openstack/neutron/commit/ee3fe4e836ca1c81e50a8324a9b5f982de4fa97f#diff-47274e5d515466fd8a373b382009b419
file: neutron/api/v2/resource.py
line: 49

[Anne Gentle (annegentle)]

Great, thanks for going through all this extra confirmation to triage this bug!

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/146008
Committed: https://git.openstack.org/cgit/openstack/api-site/commit/?id=8c1b709335f73d83b7f3bd51987619f38a727fd0
Submitter: Jenkins
Branch: master

commit 8c1b709335f73d83b7f3bd51987619f38a727fd0
Author: watanabe.isao <email address hidden>
Date: Fri Jan 9 13:01:06 2015 +0900

    Fix a wrong response code in Neutron API Reference

    Fix the response code for "create floating ip" in Neutron API Reference
    from 200 to 201.

    Change-Id: I35ef516a387f22e87787086e16653509e0794895
    Closes-Bug: #1408587