api-ref: add api-ref for bindings

Change-Id: I1e61c120570db7d7ba0b86ce36d4a1e2eefdf9fe
Related-Bug: #1580880

api-ref/source/v2/index.rst

@@ -19,6 +19,7 @@ Layer 2 Networking
 .. include:: networks.inc
 .. include:: network_segment_ranges.inc
 .. include:: ports.inc
+.. include:: port_bindings.inc
 .. include:: segments.inc
 .. include:: trunk.inc
 .. include:: trunk-details.inc

api-ref/source/v2/parameters.yaml

@@ -2538,6 +2538,12 @@ binding:vnic_type-request:
   in: body
   required: false
   type: string
+bindings:
+  description: |
+    A ``binding`` object.
+  in: body
+  required: true
+  type: object
 cidr:
   description: |
     The CIDR of the subnet.

api-ref/source/v2/port_bindings.inc

@@ -0,0 +1,131 @@
+.. -*- rst -*-
+
+============
+Port Binding
+============
+
+Expose port bindings of a virtual port to external application.
+
+Port Bindings Extended
+======================
+
+The ``Port Bindings Extended`` extension adds extra fields to ``Port Binding``
+like ``status`` and ``project id``, and allows the ``activation`` of the
+binding.
+
+Show Port Binding of a Port
+===========================
+
+.. rest_method:: GET /v2.0/ports/{port_id}/bindings
+
+Normal response codes: 200
+
+Error response codes: 401, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - port_id: port_id-path
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+    - bindings: bindings
+    - host: host
+    - profile: binding:profile
+    - vif_details: binding:vif_details
+    - vif_type: binding:vif_type
+    - vnic_type: binding:vnic_type
+
+Response Example (Admin user)
+-----------------------------
+
+.. literalinclude:: samples/port_bindings/port-binding-list-response.json
+   :language: javascript
+
+Create Port binding
+===================
+
+.. rest_method:: POST /v2.0/ports/{port_id}/bindings/
+
+Normal response codes: 201
+
+Error response codes: 400, 401, 403, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - port_id: port_id-path
+   - bindings: bindings
+   - host: host
+   - profile: binding:profile
+   - vif_details: binding:vif_details
+   - vif_type: binding:vif_type
+   - vnic_type: binding:vnic_type
+
+Request Example (Admin user)
+----------------------------
+
+.. literalinclude:: samples/port_bindings/port-binding-create-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - port_id: port_id-path
+   - bindings: bindings
+   - host: host
+   - profile: binding:profile
+   - vif_details: binding:vif_details
+   - vif_type: binding:vif_type
+   - vnic_type: binding:vnic_type
+
+Response Example (admin user)
+-----------------------------
+
+.. literalinclude:: samples/port_bindings/port-binding-create-response.json
+   :language: javascript
+
+Activate Port binding
+=====================
+
+.. rest_method:: PUT /v2.0/ports/{port_id}/bindings/{host}/activate
+
+Normal response codes: 200
+
+Error response codes: 400, 401, 404, 412
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - port_id: port_id-path
+   - host: host
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - port_id: port_id-path
+   - bindings: bindings
+   - host: host
+   - profile: binding:profile
+   - vif_details: binding:vif_details
+   - vif_type: binding:vif_type
+   - vnic_type: binding:vnic_type
+
+Response Example (admin user)
+-----------------------------
+
+.. literalinclude:: samples/port_bindings/port-binding-activate-response.json
+   :language: javascript

api-ref/source/v2/samples/port_bindings/port-binding-activate-response.json

@@ -0,0 +1,16 @@
+{
+    "binding": {
+        "host": "compute",
+        "vif_type": "ovs",
+        "vnic_type": "normal",
+        "status": "ACTIVE",
+        "profile": {},
+        "vif_details": {
+            "connectivity": "l2",
+            "port_filter": true,
+            "ovs_hybrid_plug": false,
+            "datapath_type": "system",
+            "bridge_name": "br-int"
+        }
+    }
+}

api-ref/source/v2/samples/port_bindings/port-binding-create-request.json

@@ -0,0 +1,5 @@
+{
+    "binding": {
+        "host": "compute"
+    }
+}

api-ref/source/v2/samples/port_bindings/port-binding-create-response.json

@@ -0,0 +1,16 @@
+{
+    "binding": {
+        "host": "compute",
+        "vif_type": "ovs",
+        "vnic_type": "normal",
+        "status": "INACTIVE",
+        "profile": {},
+        "vif_details": {
+            "connectivity": "l2",
+            "port_filter": true,
+            "ovs_hybrid_plug": false,
+            "datapath_type": "system",
+            "bridge_name": "br-int"
+        }
+    }
+}

api-ref/source/v2/samples/port_bindings/port-binding-list-response.json

@@ -0,0 +1,18 @@
+{
+    "bindings" : [
+        {
+            "host" : "jammy",
+            "profile" : {},
+            "status" : "ACTIVE",
+            "vif_details" : {
+                "bridge_name" : "br-int",
+                "connectivity" : "l2",
+                "datapath_type" : "system",
+                "ovs_hybrid_plug" : false,
+                "port_filter" : true
+            },
+            "vif_type" : "ovs",
+            "vnic_type" : "normal"
+        }
+   ]
+}

releasenotes/notes/add-vif-type-agilio-ovs-6bee5b2557aca10e.yaml

@@ -1,5 +1,5 @@
 ---
 features:
   - A VIF type for Agilio OVS (``VIF_TYPE_AGILIO_OVS``) has been added to
-    portbindings. This links the external Neutron plugin to the external
+    port_bindings. This links the external Neutron plugin to the external
     OS-VIF plugin in Nova.

releasenotes/notes/add-vnic-virtio-forwarder-portbinding-f7f87dfbef456ed1.yaml

@@ -1,6 +1,6 @@
 ---
 features:
-  - The ``VNIC_VIRTIO_FORWARDER`` VNIC type has been added to portbindings.
+  - The ``VNIC_VIRTIO_FORWARDER`` VNIC type has been added to port_bindings.
     This VNIC type is intended to request a low-latency virtio port inside the
     instance, likely backed by hardware acceleration. Currently the Agilio OVS
     external plugin provides support for this, with support from other vendors

releasenotes/notes/portbindings-apidef-3d7893bcb94d7f61.yaml

@@ -1,5 +1,5 @@
 ---
 features:
   - The API definition and associated constants have been
-    rehomed from ``neutron.extensions.portbindings`` to
+    rehomed from ``neutron.extensions.port_bindings`` to
-    ``neutron_lib.api.definitions.portbindings``.
+    ``neutron_lib.api.definitions.port_bindings``.