yahoo-eng-team team mailing list archive

[Florian Ermisch <0xf10e@xxxxxxxx>]

Public bug reported:

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.

** Affects: neutron
     Importance: Undecided
         Status: New


** Tags: api documentation in-stable-icehouse

** Description changed:

- 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:
+ 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
+ * 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?)
+   * "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"
+   * "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"
+   * "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
+   * "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?
+   * "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.

-- 
You received this bug notification because you are a member of Yahoo!
Engineering Team, which is subscribed to neutron.
https://bugs.launchpad.net/bugs/1418635

Title:
  Neutron API reference is inconsistent and differs from implementation

Status in OpenStack Neutron (virtual network service):
  New

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.

To manage notifications about this bug go to:
https://bugs.launchpad.net/neutron/+bug/1418635/+subscriptions