api-ref: Introduce logging api reference

This patch introduce a api reference of logging api feature.
The api is following logging api for security group spec[1].

[1] https://specs.openstack.org/openstack/neutron-specs/specs/pike/logging-API-for-security-group-rules.html

Change-Id: I7dd34d4d2ce4cac7210b10e43766d51d682764a8
Partially-implements: blueprint security-group-logging
Related-Bug: #1468366

api-ref/source/v2/index.rst

@@ -74,4 +74,8 @@ BGP/MPLS VPN Interconnection
 .. include:: bgpvpn-bgpvpns.inc
 .. include:: bgpvpn-network_associations.inc
 .. include:: bgpvpn-router_associations.inc
-.. include:: bgpvpn-port_associations.inc
+.. include:: bgpvpn-port_associations.inc
+#######
+Logging
+#######
+.. include:: logging.inc

api-ref/source/v2/logging.inc

@@ -0,0 +1,271 @@
+.. -*- rst -*-
+
+============
+Log resource
+============
+
+The ``logging`` extension lists, creates, shows information for, and updates
+log resource.
+
+List logs
+=========
+
+.. rest_method::  GET /v2.0/log/logs
+
+Lists all log resources associated with your project.
+
+Use the ``fields`` query parameter to control which fields are
+returned in the response body. Additionally, you can filter results
+by using query string parameters. For information, see `Filtering
+and Column Selection <https://wiki.openstack.org/wiki/Neutron/APIv2
+-specification#Filtering_and_Column_Selection>`__.
+
+The list might be empty.
+
+Normal response codes: 200
+
+Error response codes: 401
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - fields: fields
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - logs: logs
+   - id: log_id
+   - name: name
+   - description: description
+   - tenant_id: project_id
+   - project_id: project_id
+   - event: log_event
+   - resource_type: resource_log_type
+   - resource_id: resource_log_id
+   - target_id: resource_target_log_id
+   - enabled: log_enabled
+
+Response Example
+----------------
+
+.. literalinclude:: samples/logs/log-list-response.json
+   :language: javascript
+
+Create log
+==========
+
+.. rest_method::  POST /v2.0/log/logs
+
+Creates a log resource.
+
+Creates a log resource by using the configuration that you define in
+the request object. A response object is returned. The object
+contains a unique ID.
+
+If the caller is not an administrative user, this call returns the
+HTTP ``Forbidden (403)`` response code.
+
+Users with an administrative role can create policies on behalf of
+other projects by specifying a project ID that is different than
+their own.
+
+Normal response codes: 201
+
+Error response codes: 400, 401, 403, 409
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - log: log
+   - name: name-request
+   - description: description-request
+   - tenant_id: project_id-request
+   - project_id: project_id-request
+   - event: log_event-request
+   - resource_type: resource_log_type
+   - resource_id: resource_log_id-request
+   - target_id: resource_target_log_id-request
+   - enabled: log_enabled-request
+
+Request Example
+---------------
+
+.. literalinclude:: samples/logs/log-create-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - log: log
+   - id: log_id
+   - name: name
+   - description: description
+   - tenant_id: project_id
+   - project_id: project_id
+   - event: log_event
+   - resource_type: resource_log_type
+   - resource_id: resource_log_id
+   - target_id: resource_target_log_id
+   - enabled: log_enabled
+
+Request Example
+---------------
+
+.. literalinclude:: samples/logs/log-create-response.json
+   :language: javascript
+
+Show log
+========
+
+.. rest_method::  GET /v2.0/log/logs/{log_id}
+
+Shows details log resource.
+
+Normal response codes: 200
+
+Error response codes: 401, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - log_id: log_id-path
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - log: log
+   - id: log_id
+   - name: name
+   - description: description
+   - tenant_id: project_id
+   - project_id: project_id
+   - event: log_event
+   - resource_type: resource_log_type
+   - resource_id: resource_log_id
+   - target_id: resource_target_log_id
+   - enabled: log_enabled
+
+Response Example
+----------------
+
+.. literalinclude:: samples/logs/log-show-response.json
+   :language: javascript
+
+Update log
+==========
+
+.. rest_method::  PUT /v2.0/log/logs/{log_id}
+
+Updates a log resource.
+
+Normal response codes: 200
+
+Error response codes: 400, 401, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - log_id: log_id-path
+   - log: log
+   - name: name-request
+   - description: description-request
+   - enabled: log_enabled-request-put
+
+Request Example
+---------------
+
+.. literalinclude:: samples/logs/log-update-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - log: log
+   - id: log_id
+   - name: name
+   - description: description
+   - tenant_id: project_id
+   - project_id: project_id
+   - event: log_event
+   - resource_type: resource_log_type
+   - resource_id: resource_log_id
+   - target_id: resource_target_log_id
+   - enabled: log_enabled
+
+Response Example
+----------------
+
+.. literalinclude:: samples/logs/log-update-response.json
+   :language: javascript
+
+Delete log
+==========
+
+.. rest_method::  DELETE /v2.0/log/logs/{log_id}
+
+Deletes a log resource.
+
+Normal response codes: 204
+
+Error response codes: 400, 401, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - log_id: log_id-path
+
+Response
+--------
+
+There is no body content for the response of a successful DELETE request.
+
+=================
+Loggable resource
+=================
+
+List loggable resources
+=======================
+
+.. rest_method::  GET /v2.0/log/loggable-resources
+
+Lists all resource log types are supporting.
+
+Normal response codes: 200
+
+Error response codes: 401
+
+Request
+-------
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - loggable_resources: loggable_resources
+   - type: resource_log_type
+
+Response Example
+----------------
+
+.. literalinclude:: samples/logs/loggable_resources-list-response.json
+   :language: javascript

api-ref/source/v2/parameters.yaml

@@ -133,6 +133,12 @@ loadbalancer-id-path:
   in: path
   required: true
   type: string
+log_id-path:
+  description: |
+    The ID of the log resource.
+  in: path
+  required: true
+  type: string
 logging_resource_id:
   description: |
     The ID of the logging resource.
@@ -3126,6 +3132,58 @@ location:
   in: body
   required: true
   type: string
+log:
+  description: |
+    A ``log`` object.
+  in: body
+  required: true
+  type: object
+log_enabled:
+  description: |
+    Indicates whether this log object is enabled or disabled.
+  in: body
+  required: true
+  type: boolean
+log_enabled-request:
+  description: |
+    Indicates whether this log object is enabled or disabled.
+    Default is true.
+  in: body
+  required: false
+  type: boolean
+log_enabled-request-put:
+  description: |
+    Indicates whether this log object is enabled or disabled.
+  in: body
+  required: false
+  type: boolean
+log_event:
+  description: |
+    Type of security events to log.
+    ``ACCEPT``, ``DROP``, or ``ALL``.
+  in: body
+  required: true
+  type: string
+log_event-request:
+  description: |
+    Type of security events to log.
+    ``ACCEPT``, ``DROP``, or ``ALL``.
+    Default is ``ALL``.
+  in: body
+  required: false
+  type: string
+log_id:
+  description: |
+    The ID of the log object.
+  in: body
+  required: true
+  type: string
+loggable_resources:
+  description: |
+    A list of ``loggable_resource`` object.
+  in: body
+  required: true
+  type: object
 logging_resource:
   description: |
     A ``logging_resource`` object.
@@ -3163,6 +3221,12 @@ logging_resources:
   in: body
   required: true
   type: array
+logs:
+  description: |
+    A list of ``log`` objects.
+  in: body
+  required: true
+  type: array
 mac_address:
   description: |
     The MAC address of the port.
@@ -4575,6 +4639,36 @@ resource-rel:
   in: body
   required: true
   type: string
+resource_log_id:
+  description: |
+    The ID of resource log (e.g security group ID).
+  in: body
+  required: true
+  type: string
+resource_log_id-request:
+  description: |
+    The ID of resource log (e.g security group ID).
+  in: body
+  required: false
+  type: string
+resource_log_type:
+  description: |
+    The resource log type such as 'security_group'.
+  in: body
+  required: true
+  type: string
+resource_target_log_id:
+  description: |
+    The ID of resource target log such as port ID.
+  in: body
+  required: true
+  type: string
+resource_target_log_id-request:
+  description: |
+    The ID of resource target log such as port ID.
+  in: body
+  required: false
+  type: string
 resources:
   description: |
     List of resource objects.

api-ref/source/v2/samples/logs/log-create-request.json

@@ -0,0 +1,7 @@
+{
+    "log": {
+        "name": "security group log",
+        "description": "Log for project demo.",
+        "resource_type": "security_group"
+    }
+}

api-ref/source/v2/samples/logs/log-create-response.json

@@ -0,0 +1,14 @@
+{
+    "log": {
+        "name": "security group log",
+        "description": "Log for project demo.",
+        "id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
+        "project_id": "92a5a4f4245a4abbafacb7ca73b027b0",
+        "tenant_id": "92a5a4f4245a4abbafacb7ca73b027b0",
+        "enabled": true,
+        "resource_type": "security_group",
+        "resource_id": null,
+        "target_id": null,
+        "event": "ALL"
+    }
+}

api-ref/source/v2/samples/logs/log-list-response.json

@@ -0,0 +1,16 @@
+{
+    "logs": [
+        {
+            "name": "security group log",
+            "description": "Log for project demo.",
+            "id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
+            "project_id": "92a5a4f4245a4abbafacb7ca73b027b0",
+            "tenant_id": "92a5a4f4245a4abbafacb7ca73b027b0",
+            "enabled": true,
+            "resource_type": "security_group",
+            "resource_id": null,
+            "target_id": null,
+            "event": "ALL"
+        }
+    ]
+}

api-ref/source/v2/samples/logs/log-show-response.json

@@ -0,0 +1,14 @@
+{
+    "log": {
+        "name": "security group log",
+        "description": "Log for project demo.",
+        "id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
+        "project_id": "8d4c70a21fed4aeba121a1a429ba0d04",
+        "tenant_id": "8d4c70a21fed4aeba121a1a429ba0d04",
+        "enabled": true,
+        "resource_type": "security_group",
+        "resource_id": null,
+        "target_id": null,
+        "event": "ACCEPT"
+    }
+}

api-ref/source/v2/samples/logs/log-update-request.json

@@ -0,0 +1,5 @@
+{
+    "log": {
+        "enabled": false
+    }
+}

api-ref/source/v2/samples/logs/log-update-response.json

@@ -0,0 +1,14 @@
+{
+    "log": {
+        "name": "security group log",
+        "description": "Log for project demo.",
+        "id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
+        "project_id": "8d4c70a21fed4aeba121a1a429ba0d04",
+        "tenant_id": "8d4c70a21fed4aeba121a1a429ba0d04",
+        "enabled": false,
+        "resource_type": "security_group",
+        "resource_id": null,
+        "target_id": null,
+        "event": "DROP"
+    }
+}

api-ref/source/v2/samples/logs/loggable_resources-list-response.json

@@ -0,0 +1,7 @@
+{
+    "loggable_resources": [
+        {
+            "type": "security_group"
+        }
+    ]
+}

releasenotes/notes/logging-api-ref-fafb884367ca60a2.yaml

@@ -0,0 +1,3 @@
+---
+features:
+  - API reference for the logging extension for ``security_group`` resource.