Update associate fip API

1. Change to return 204 (No Content), as the POST method doesn't
result in a resource that can be identified by a URL
2. Add API docs for associate fip API.

Change-Id: I8b384dcd10c9c5f5f06ee55c3fa0a846ba7d3526

api-ref/source/v1/instance_networks.inc

@@ -36,3 +36,33 @@ Response
 **Example instance network:**
 
 .. literalinclude:: samples/instances/instance-get-network-response.json
+
+
+Add (Associate) Floating IP
+===========================
+
+.. rest_method:: POST /v1/instances/{instance_uuid}/networks/floatingips
+
+Adds a floating IP address to an instance, which associates
+that address with the instance.
+
+If an instance is connected to multiple networks, you can associate a
+floating IP address with a specific fixed IP address by using the
+optional ``fixed_address`` parameter.
+
+Normal response code: 204
+
+Error codes: 400,401,403,404,409
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - instance_uuid: instance_ident
+    - address: address
+    - fixed_address: fixed_address
+
+**Example request to Add (Associate) Floating IP to an instance:**
+
+.. literalinclude:: samples/instances/instance-associate-fip-req.json

api-ref/source/v1/parameters.yaml

@@ -64,6 +64,12 @@ user_id:
 
 # variables in body
 
+address:
+  description: |
+    The floating IP address.
+  in: body
+  required: true
+  type: string
 availability_zone:
   description: |
     The availability zone from which to launch the instance. When you provision resources,
@@ -107,6 +113,12 @@ extra:
   in: body
   required: false
   type: object
+fixed_address:
+  description: |
+    The fixed IP address with which you want to associate the floating IP address.
+  in: body
+  required: false
+  type: string
 imageRef:
   description: |
     The UUID of the image to use for your instance.

api-ref/source/v1/samples/instances/instance-associate-fip-req.json

@@ -0,0 +1,4 @@
+{
+    "address": "172.24.4.10",
+    "fixed_address": "11.0.0.5"
+}

mogan/api/controllers/v1/instances.py

@@ -123,16 +123,6 @@ class InstanceStatesController(InstanceControllerBase):
         pecan.response.location = link.build_url('instances', url_args)
 
 
-class FloatingIP(base.APIBase):
-    """API representation of the floatingip information for an instance."""
-
-    id = types.uuid
-    """The ID of the floating IP"""
-
-    port_id = types.uuid
-    """The ID of the port that associated to"""
-
-
 class FloatingIPController(InstanceControllerBase):
     """REST controller for Instance floatingips."""
 
@@ -141,8 +131,8 @@ class FloatingIPController(InstanceControllerBase):
         self.network_api = network.API()
 
     @policy.authorize_wsgi("mogan:instance", "associate_floatingip", False)
-    @expose.expose(FloatingIP, types.uuid, types.jsontype,
-                   status_code=http_client.CREATED)
+    @expose.expose(None, types.uuid, body=types.jsontype,
+                   status_code=http_client.NO_CONTENT)
     def post(self, instance_uuid, floatingip):
         """Add(Associate) Floating Ip.
 
@@ -197,7 +187,7 @@ class FloatingIPController(InstanceControllerBase):
                                 'IPv4 fixed_ip: %s'), fixed_address)
 
         try:
-            fip = self.network_api.associate_floating_ip(
+            self.network_api.associate_floating_ip(
                 pecan.request.context, floating_address=address,
                 port_id=port_id, fixed_address=fixed_address)
         except exception.FloatingIpNotFoundForAddress as e:
@@ -216,12 +206,6 @@ class FloatingIPController(InstanceControllerBase):
             raise wsme.exc.ClientSideError(
                 msg, status_code=http_client.BAD_REQUEST)
 
-        # Set the HTTP Location Header, user can get the floating ips
-        # by locaton.
-        url_args = '/'.join([instance_uuid, 'networks'])
-        pecan.response.location = link.build_url('instances', url_args)
-        return FloatingIP(id=fip['id'], port_id=fip['port_id'])
-
     @policy.authorize_wsgi("mogan:instance", "disassociate_floatingip")
     @expose.expose(None, types.uuid, types.jsontype,
                    status_code=http_client.NO_CONTENT)
@@ -288,7 +272,7 @@ class InstanceNetworks(base.APIBase):
 class InstanceNetworksController(InstanceControllerBase):
     """REST controller for Instance networks."""
 
-    floatingip = FloatingIPController()
+    floatingips = FloatingIPController()
     """Expose floatingip as a sub-element of networks"""
 
     @policy.authorize_wsgi("mogan:instance", "get_networks")

mogan/network/api.py

@@ -177,7 +177,6 @@ class API(object):
         param = {'port_id': port_id,
                  'fixed_ip_address': fixed_address}
         client.update_floatingip(fip['id'], {'floatingip': param})
-        return fip
 
     def disassociate_floating_ip(self, context, address):
         """Disassociate a floating IP from the instance."""