[api-ref]Neutron API reference is inconsistent and differs from implementation

Bug #1418635 reported by Florian Ermisch
6
This bug affects 1 person
Affects Status Importance Assigned to Milestone
neutron
Fix Released
Medium
Unassigned

Bug Description

I'm implementing modules for SaltStack (not yet on GitHub) to create entities in OpenStack Neutron and came across quite a few problems
with the API documentation:

* Link "Filtering and Column Selection" to
  http://docs.openstack.org/api/openstack-network/2.0/content/filtering.html
  404s

* Section http://developer.openstack.org/api-ref-networking-v2.html#subnets

  * "POST /v2.0/subnets" aka "Create subnet"
    - 'id' is listed to be an optional parameter but the Neutron-API in
      Icehouse refuses to set a user-selected ID
    - parameters 'dns_nameservers' and 'host_routes' missing from
      documentation (undocumented extensions?)

  * "GET /v2.0/subnets" aka "List subnets"
    - can't filter by "allocation_pools" or "enable_dhcp"

  * "PUT /v2.0/subnets/​{subnet_id}​" aka "Update subnet"
    - parameters "allocation_pools", "network_id", "tenant_id", "id" listed
      as optional request parameters but Neutron-API in Icehouse returns
      "Cannot update read-only attribute $PARAMETER"

* Section http://developer.openstack.org/api-ref-networking-v2.html#networks

  * "GET /v2.0/networks" aka "List networks"
    - parameter "shared" is ignored as a filter

* Section http://developer.openstack.org/api-ref-networking-v2.html#layer3

  * "POST /v2.0/routers" aka "Create router"
    - Description states "router:external" and "external_gateway_info" are
      valid request parameters but they're not listed in the table of
      request parameters
    - What's the parameter router described as "A router object." supposed
      to be? A router object in JSON/XML notation inside a router object in
      JSON/XML notation?

I'll probably add more when implementing functions for managing routers in Neutron.

Florian Ermisch (0xf10e)
description: updated
Revision history for this message
Florian Ermisch (0xf10e) wrote :

* Section http://developer.openstack.org/api-ref-networking-v2.html#layer3
  * "PUT /v2.0/routers/​{router_id}​/add_router_interface" aka "Add interface to router"
    - "If you specify a subnet ID in the request body", "If you specify a port ID in the request body"
      but no parameters "subnet_id", port_id in table of request parameters

no longer affects: neutron
Edgar Magana (emagana)
Changed in openstack-api-site:
assignee: nobody → Edgar Magana (emagana)
Revision history for this message
Anne Gentle (annegentle) wrote :
Changed in openstack-api-site:
status: New → Confirmed
importance: Undecided → Medium
Atsushi SAKAI (sakaia)
tags: added: neutron
Atsushi SAKAI (sakaia)
affects: openstack-api-site → neutron
summary: - Neutron API reference is inconsistent and differs from implementation
+ [api-ref]Neutron API reference is inconsistent and differs from
+ implementation
Revision history for this message
Umair Ahmad (umairr) wrote :

I want to get assigned to this bug

Umair Ahmad (umairr)
Changed in neutron:
assignee: Edgar Magana (emagana) → Umair Ahmad (umairr)
Umair Ahmad (umairr)
Changed in neutron:
assignee: Umair Ahmad (umairr) → nobody
bhavana Kappala (bhavan)
Changed in neutron:
assignee: nobody → bhavana Kappala (bhavan)
Revision history for this message
bhavana Kappala (bhavan) wrote :
Download full text (3.3 KiB)

Hi Florian Ermisch,

Please find my analysis inline

1) "POST /v2.0/subnets" aka "Create subnet"
    - 'id' is listed to be an optional parameter but the Neutron-API in
      Icehouse refuses to set a user-selected ID
    - parameters 'dns_nameservers' and 'host_routes' missing from
      documentation (undocumented extensions?)

----> "ID" parameter cannot be given as an input for the subnet creation, the same can be observed in the Request table of the below link
      http://developer.openstack.org/api-ref/networking/v2/index.html?expanded=create-subnet-detail#subnets

      parameters 'dns_nameservers' and 'host_routes' are mentioned in the documentation link provided.
      http://developer.openstack.org/api-ref/networking/v2/index.html?expanded=create-subnet-detail#subnets

2) "GET /v2.0/subnets" aka "List subnets"
    - can't filter by "allocation_pools" or "enable_dhcp"

----> We are able to filter by "allocation_pools" and "enable_dhcp" seperately, please find the curl requests for the same

 curl -g -i -X GET http://192.168.122.58:9696/v2.0/subnets.json?fields=allocation_pools -H "User-Agent: python-neutronclient" -H "Accept: application/json" -H "X-Auth-Token: $OS_TOKEN"

curl -g -i -X GET http://192.168.122.58:9696/v2.0/subnets.json?fields=enable_dhcp -H "User-Agent: python-neutronclient" -H "Accept: application/json" -H "X-Auth-Token: $OS_TOKEN"

3)"PUT /v2.0/subnets/​{subnet_id}​" aka "Update subnet"
    - parameters "allocation_pools", "network_id", "tenant_id", "id" listed
      as optional request parameters but Neutron-API in Icehouse returns
      "Cannot update read-only attribute $PARAMETER"

----> We are able to update the "allocation_pools", find the curl request for the same.
      "network_id", "tenant_id", "id" attributes cannot be modified in the update request.

curl -s http://192.168.122.58:9696/v2.0/subnets/5b157240-714e-46b5-ad60-ad379e8baf2f -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "X-Auth-Token: $OS_TOKEN" -d '{"subnet": { "allocation_pools": [{ "start":"10.20.25.2","end":"10.20.25.253"}]}}'

4)* "GET /v2.0/networks" aka "List networks"
    - parameter "shared" is ignored as a filter

----> To get the JSON response with the networks in which shared attribute is true this is the following CURL command where "shared" is added as a filter.

We are able to filter the networks by specifying the particular attribute (ex: shared) in the GET request as specified below

curl -g -i -X GET http://192.168.122.58:9696/v2.0/networks.json?shared=true -H "User-Agent: python-neutronclient" -H "Accept: application/json" -H "X-Auth-Token: $OS_TOKEN"

5) * "POST /v2.0/routers" aka "Create router"
    - Description states "router:external" and "external_gateway_info" are
      valid request parameters but they're not listed in the table of
      request parameters
    - What's the parameter router described as "A router object." supposed
      to be? A router object in JSON/XML notation inside a router object in
      JSON/XML notation?

----> "router:external" this attribute is present in the "networks" Response Body but not in the "Router" REsponse body.
      "external_gat...

Read more...

bhavana Kappala (bhavan)
Changed in neutron:
assignee: bhavana Kappala (bhavan) → nobody
Revision history for this message
Brian Haley (brian-haley) wrote :

Looks like all these have been fixed, please open a new bug if other API issues are found.

Changed in neutron:
status: Confirmed → Fix Released
To post a comment you must log in.
This report contains Public information  
Everyone can see this information.

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.