#%RAML 0.8
title: Neutron Shared IPs API
version: v2.0
baseUri: https://{neutronUri}/{version}/
mediaType: application/json
traits:
    - secured:
        headers:
            X-Auth-Token:
                description: Token for request's tenant
                required: true
                type: string
/ip_addresses:
    displayName: Neutron IP Addresses
    description: A collection of IP addresses
    is: [ secured ]
    get:
        description: List all IPs for a given tenant
        queryParameters:
            # All from the IP addresses response
            id:
                description: filters by IP addresses UUID
                type: string
            network_id:
                description: filters IP addresses by their network UUID
                type: string
            address:
                description: filters IP address by their address
                type: string
            # Query will support only one port ID
            port_ids:
                description: filters IP addresses by a port UUID
                type: string
            subnet_id:
                description: filters IP addresses by their subnet UUID
                type: string
            tenant_id:
                description: filters IP addresses by their user tenant ID
                type: string
            version:
                description: filters IP addresses by their version 4 or 6
                type: int
            type:
                description: filters IP addresses by their type, for ex. fixed
                type: string
            
            # Plus the following /ip_addresses/{id}/ports child resources
            device_id:
                description: filters IP addresses by their ports' device_id
                type: string
            service:
                description: filters IP addresses by their service
                type: string
        responses:
            200:
                description: ok
                body:
                    application/json:
                        example: |
                            {"ip_addresses": [{
                                "id": "4cacd68e-d7aa-4ff2-96f4-5c6f57dba737",
                                "network_id": "6870304a-7212-443f-bd0c-089c886b44df",
                                "address": "192.168.10.1",
                                "port_ids": ['2f693cca-7383-45da-8bae-d26b6c2d6718'],
                                "subnet_id": "f11687e8-ef0d-4207-8e22-c60e737e473b",
                                "tenant_id": "2345678",
                                "version": "4",
                                "type": "fixed"}]}
    post:
        description: |
            Neutron creates an IP address on a specified network (network_id) with a specified IP version (version).
            A list of device_ids may be optionally specified to create the IP address and added to their respective ports.
            A list of port_ids may be optionally specified to create the IP address and added to the specified ports.
            At least one of device_ids or port_ids must be specified.
            Defaults all ports' service to "none".
        body:
            application/json:
                  example: |
                      {
                          "ip_address": {
                              "network_id": "fda61e0b-a410-49e8-ad3a-64c595618c7e",
                              "version": 4,
                              "port_ids": ["6200d533-a42b-4c04-82a1-cc14dbdbf2de"]}
                      }
        responses:
            201:
                description: created
                body:
                    application/json:
                        example: |
                            {
                                "ip_address": {
                                    "id": "4cacd68e-d7aa-4ff2-96f4-5c6f57dba737",
                                    "network_id": "fda61e0b-a410-49e8-ad3a-64c595618c7e",
                                    "address": "192.168.10.1",
                                    "port_ids": ["6200d533-a42b-4c04-82a1-cc14dbdbf2de"],
                                    "subnet_id": "f11687e8-ef0d-4207-8e22-c60e737e473b",
                                    "tenant_id": "2345678",
                                    "version": "4",
                                    "type": "fixed"}
                            }
            400:
                description: |
                    bad input
                    * IP version not 4 nor 6
                    * Ambiguous ports: multiple ports associated with a single device_id (devices with multiple ports must use the port_ids field)
            401:
                description: |
                    unauthorized
                    * Cannot create IP address on other tenant's network (can create IP address on provider network)
            404:
                description: |
                    Not found
                    * Network not found.
                    * Subnet with desired IP version not found.
                    * Ports not found.
    /{ipAddressId}:
        description: A specific IP address, a member of the IP addresses collection
        get:
            description: shows a specific IP address
            responses:
                200:
                    description: ok
                    body:
                        application/json:
                            example: |
                                {"ip_address": {
                                    "id": "4cacd68e-d7aa-4ff2-96f4-5c6f57dba737",
                                    "network_id": "6870304a-7212-443f-bd0c-089c886b44df",
                                    "address": "192.168.10.1",
                                    "port_ids": ['2f693cca-7383-45da-8bae-d26b6c2d6718'],
                                    "subnet_id": "f11687e8-ef0d-4207-8e22-c60e737e473b",
                                    "tenant_id": "2345678",
                                    "version": "4",
                                    "type": "fixed"}
                404:
                    description: not found, e.g. another tenant's IP address
        put:
            description: |
                update an IP address, e.g. to change ports. This will eliminate any previous associations to ports.
            body:
                application/json:
                    example: |
                        {"ip_address": {
                            "port_ids": ['275b0516-206f-4421-8e42-1d3d1e4e9fb2', '66811c0a-fdbd-49d4-b1dd-f0f15a329744']}
            responses:
                200:
                    description: updated
                404:
                    description: |
                        not found
                        * attempting to update another tenant's IP address
                        * ports not found
        delete:
            description: delete an IP address
            responses:
                204:
                    description: deleted
                400:
                    description: |
                        bad request
                        * attempting to delete an IP with a `service != "none"` port (tenant should disassociate on nova-side first)
                        * attempting to delete a provider network's IP address
                404:
                    description: |
                        not found
                        * attempting to delete another tenant's IP address
        /ports/:
            description: |
                Collection of ports for a given IP address.
                This URI will be hidden to tenants.
            get:
                description: |
                    List the ports associated with an IP address
                queryParameters:
                    id:
                        description: filters ports for a specific ip_address_id by their UUID
                        type: string
                    device_id:
                        description: filter ports for a specific ip_address_id by their device_id
                        type: string
                    service:
                        description: filters ports for a specific ip_address_id by their service
                        type: string
                responses:
                    200:
                        description: ok
                        body:
                            application/json:
                                example: |
                                    {"ip_addresses_ports": [{"id": "dce3dca6-2cba-4e00-95e9-748587f94620", "service": "compute",
                                    "device_id": "3b150725-cebb-492d-8286-9dbe80b54a87"}]}
                    404:
                        description: not found
            post:
                responses:
                    501:
                        description: not implemented
            /{portId}:
                get:
                    description: Shows a specific IP address service
                    body:
                        application/json:
                            example: |
                                {"ip_addresses_port": {"id": "dce3dca6-2cba-4e00-95e9-748587f94620", "service": "compute",
                                "device_id": "3b150725-cebb-492d-8286-9dbe80b54a87"}}
                put:
                    description: |
                        Internal call from nova to neutron to update an IP address's service to either "none" or "compute"
                    body:
                        application/json:
                            example: |
                                {"ip_addresses_port": {"service": "compute"}}
                    responses:
                        200:
                            description: updated
                        400:
                            description: |
                                bad input
                                * service string too long (max 256, for example)
                        401:
                            description: |
                                unauthorized, e.g. only nova can make this PUT
                        404:
                            description: |
                                not found, e.g.where this port_id=portId does not exist or belongs to other tenant
                delete:
                    responses:
                        501:
                            description: not implemented
