Add documentation for DBaaS Kafka support (#826)

* Add Kafka to database options and update example to current API response.

* Add kafka to engine enum.

* Add Kafka user details.

* Add Kafka topic operations.

* Make the linter happy.

* topic update body is wrapped.

* Add some additional detail to topic config model

* compact_delete is a vaild cleanup_policy

specification/DigitalOcean-public.v2.yaml

@@ -862,6 +862,20 @@ paths:
     put:
       $ref: 'resources/databases/databases_upgrade_major_version.yml'
 
+  /v2/databases/{database_cluster_uuid}/topics:
+    get:
+      $ref: 'resources/databases/databases_list_kafka_topics.yml'
+    post:
+      $ref: 'resources/databases/databases_create_kafka_topic.yml'
+
+  /v2/databases/{database_cluster_uuid}/topics/{topic_name}:
+    get:
+       $ref: 'resources/databases/databases_get_kafka_topic.yml'
+    put:
+       $ref: 'resources/databases/databases_update_kafka_topic.yml'
+    delete:
+       $ref: 'resources/databases/databases_delete_kafka_topic.yml'
+
   /v2/domains:
     get:
       $ref: 'resources/domains/domains_list.yml'

specification/resources/databases/databases_add_user.yml

@@ -11,6 +11,9 @@ description: |
   When adding a user to a MySQL cluster, additional options can be configured in the
   `mysql_settings` object.
 
+  When adding a user to a Kafka cluster, additional options can be configured in
+  the `settings` object.
+
   The response will be a JSON object with a key called `user`. The value of this will be an
   object that contains the standard attributes associated with a database user including
   its randomly generated password.
@@ -52,6 +55,21 @@ requestBody:
             name: my-readonly
             readonly: true
 
+        Add New User with Kafka ACLs:
+          value:
+            name: app-03
+            settings:
+              acl:
+              - id: acl128aaaa99239
+                permission: produceconsume
+                topic: customer-events
+              - id: acl293098flskdf
+                permission: produce
+                topic: customer-events.*
+              - id: acl128ajei20123
+                permission: consume
+                topic: customer-events
+
 responses:
   '201':
     $ref: 'responses/user.yml'

specification/resources/databases/databases_create_kafka_topic.yml

@@ -0,0 +1,57 @@
+operationId: databases_create_kafka_topic
+
+summary:  Create Topic for a Kafka Cluster
+
+description: |
+  To create a topic attached to a Kafka cluster, send a POST request to
+  `/v2/databases/$DATABASE_ID/topics`.
+
+  The result will be a JSON object with a `topic` key.
+
+tags:
+  - Databases
+
+parameters:
+  - $ref: 'parameters.yml#/database_cluster_uuid'
+
+requestBody:
+  content:
+    application/json:
+      schema:
+        allOf:
+          - $ref: 'models/kafka_topic_create.yml'
+        required:
+          - name
+      example:
+        name: customer-events
+        partitions: 3
+        replication: 2
+        config:
+          retention_bytes: -1
+          retention_ms: 100000
+
+responses:
+  '201':
+    $ref: 'responses/kafka_topic.yml'
+
+  '401':
+    $ref: '../../shared/responses/unauthorized.yml'
+
+  '404':
+    $ref: '../../shared/responses/not_found.yml'
+
+  '429':
+    $ref: '../../shared/responses/too_many_requests.yml'
+
+  '500':
+    $ref: '../../shared/responses/server_error.yml'
+
+  default:
+    $ref: '../../shared/responses/unexpected_error.yml'
+
+x-codeSamples:
+  - $ref: 'examples/curl/databases_create_topic.yml'
+
+security:
+  - bearer_auth:
+    - 'write'

specification/resources/databases/databases_delete_kafka_topic.yml

@@ -0,0 +1,44 @@
+operationId: databases_delete_kafka_topic
+
+summary: Delete Topic for a Kafka Cluster
+
+description: |
+  To delete a single topic within a Kafka cluster, send a DELETE request
+  to `/v2/databases/$DATABASE_ID/topics/$TOPIC_NAME`.
+
+  A status of 204 will be given. This indicates that the request was
+  processed successfully, but that no response body is needed.
+
+tags:
+  - Databases
+
+parameters:
+  - $ref: 'parameters.yml#/database_cluster_uuid'
+  - $ref: 'parameters.yml#/kafka_topic_name'
+
+responses:
+  '204':
+    $ref: '../../shared/responses/no_content.yml'
+
+  '401':
+    $ref: '../../shared/responses/unauthorized.yml'
+
+  '404':
+    $ref: '../../shared/responses/not_found.yml'
+
+  '429':
+    $ref: '../../shared/responses/too_many_requests.yml'
+
+  '500':
+    $ref: '../../shared/responses/server_error.yml'
+
+  default:
+    $ref: '../../shared/responses/unexpected_error.yml'
+
+x-codeSamples:
+  - $ref: 'examples/curl/databases_delete_topic.yml'
+
+security:
+  - bearer_auth:
+    - 'write'
+

specification/resources/databases/databases_get_kafka_topic.yml

@@ -0,0 +1,43 @@
+operationId: databases_get_kafka_topic
+
+summary: Get Topic for a Kafka Cluster
+
+description: |
+  To retrieve a given topic by name from the set of a Kafka cluster's topics,
+  send a GET request to `/v2/databases/$DATABASE_ID/topics/$TOPIC_NAME`.
+
+  The result will be a JSON object with a `topic` key.
+
+tags:
+  - Databases
+
+parameters:
+  - $ref: 'parameters.yml#/database_cluster_uuid'
+  - $ref: 'parameters.yml#/kafka_topic_name'
+
+responses:
+  '200':
+    $ref: 'responses/kafka_topic.yml'
+
+  '401':
+    $ref: '../../shared/responses/unauthorized.yml'
+
+  '404':
+    $ref: '../../shared/responses/not_found.yml'
+
+  '429':
+    $ref: '../../shared/responses/too_many_requests.yml'
+
+  '500':
+    $ref: '../../shared/responses/server_error.yml'
+
+  default:
+    $ref: '../../shared/responses/unexpected_error.yml'
+
+x-codeSamples:
+  - $ref: 'examples/curl/databases_get_topic.yml'
+
+security:
+  - bearer_auth:
+    - 'read'
+

specification/resources/databases/databases_get_user.yml

@@ -11,9 +11,11 @@ description: |
   The response will be a JSON object with a `user` key. This will be set to an object
   containing the standard database user attributes.
 
-  For MySQL clusters, additional options will be contained in the mysql_settings
+  For MySQL clusters, additional options will be contained in the `mysql_settings`
   object.
 
+  For Kafka clusters, additional options will be contained in the `settings` object.
+
 tags:
   - Databases
 

specification/resources/databases/databases_list_kafka_topics.yml

@@ -0,0 +1,42 @@
+operationId: databases_list_kafka_topics
+
+summary:  List Topics for a Kafka Cluster
+
+description: |
+  To list all of a Kafka cluster's topics, send a GET request to
+  `/v2/databases/$DATABASE_ID/topics`.
+
+  The result will be a JSON object with a `topics` key.
+
+tags:
+  - Databases
+
+parameters:
+  - $ref: 'parameters.yml#/database_cluster_uuid'
+
+responses:
+  '200':
+    $ref: 'responses/kafka_topics.yml'
+
+  '401':
+    $ref: '../../shared/responses/unauthorized.yml'
+
+  '404':
+    $ref: '../../shared/responses/not_found.yml'
+
+  '429':
+    $ref: '../../shared/responses/too_many_requests.yml'
+
+  '500':
+    $ref: '../../shared/responses/server_error.yml'
+
+  default:
+    $ref: '../../shared/responses/unexpected_error.yml'
+
+x-codeSamples:
+  - $ref: 'examples/curl/databases_list_topics.yml'
+
+security:
+  - bearer_auth:
+    - 'read'
+

specification/resources/databases/databases_update_kafka_topic.yml

@@ -0,0 +1,60 @@
+operationId: databases_update_kafka_topic
+
+summary:  Update Topic for a Kafka Cluster
+
+description: |
+  To update a topic attached to a Kafka cluster, send a PUT request to
+  `/v2/databases/$DATABASE_ID/topics/$TOPIC_NAME`.
+
+  The result will be a JSON object with a `topic` key.
+
+tags:
+  - Databases
+
+parameters:
+  - $ref: 'parameters.yml#/database_cluster_uuid'
+  - $ref: 'parameters.yml#/kafka_topic_name'
+
+requestBody:
+  content:
+    application/json:
+      schema:
+        allOf:
+          - $ref: 'models/kafka_topic_update.yml'
+        required:
+          - topic
+      example:
+        topic:
+          name: customer-events
+          partitions: 3
+          replication: 2
+          config:
+            retention_bytes: -1
+            retention_ms: 100000
+
+responses:
+  '200':
+    $ref: 'responses/kafka_topic.yml'
+
+  '401':
+    $ref: '../../shared/responses/unauthorized.yml'
+
+  '404':
+    $ref: '../../shared/responses/not_found.yml'
+
+  '429':
+    $ref: '../../shared/responses/too_many_requests.yml'
+
+  '500':
+    $ref: '../../shared/responses/server_error.yml'
+
+  default:
+    $ref: '../../shared/responses/unexpected_error.yml'
+
+x-codeSamples:
+  - $ref: 'examples/curl/databases_update_topic.yml'
+
+security:
+  - bearer_auth:
+    - 'write'
+

specification/resources/databases/examples/curl/databases_create_topic.yml

@@ -0,0 +1,7 @@
+lang: cURL
+source: |-
+  curl -X POST \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    -d '{"name":"customer-events", "partition_count":3, "replication_factor": 3, "config": {"retentionMS": 1000000}}' \
+    "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/topics"

specification/resources/databases/examples/curl/databases_delete_topic.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X DELETE \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/topics/customer-events"

specification/resources/databases/examples/curl/databases_get_topic.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/topics/customer-events"

specification/resources/databases/examples/curl/databases_list_topics.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/topics"

specification/resources/databases/examples/curl/databases_update_topic.yml

@@ -0,0 +1,7 @@
+lang: cURL
+source: |-
+  curl -X PUT \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    -d '{"topic":{"name":"customer-events", "partition_count":3, "replication_factor": 3, "config": {"retentionMS": 1000000}}}' \
+    "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/topics/customer-events"

specification/resources/databases/models/database_cluster.yml

@@ -19,9 +19,11 @@ properties:
       - mysql
       - redis
       - mongodb
+      - kafka
     description: >-
       A slug representing the database engine used for the cluster. The possible values
-      are: "pg" for PostgreSQL, "mysql" for MySQL, "redis" for Redis, and "mongodb" for MongoDB.
+      are: "pg" for PostgreSQL, "mysql" for MySQL, "redis" for Redis, "mongodb" for MongoDB,
+      and "kafka" for Kafka.
   version:
     type: string
     example: '8'

specification/resources/databases/models/database_user.yml

@@ -23,8 +23,23 @@ properties:
     description: A randomly generated password for the database user.
     readOnly: true
 
+  access_cert:
+    type: string
+    example: "-----BEGIN CERTIFICATE-----\nMIIFFjCCA/6gAwIBAgISA0AznUJmXhu08/89ZuSPC/kRMA0GCSqGSIb3DQEBCwUA\nMEoxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MSMwIQYDVQQD\nExpMZXQncyBFbmNyeXB0IEF1dGhvcml0eSBYMzAeFw0xNjExMjQwMDIzMDBaFw0x\nNzAyMjIwMDIzMDBaMCQxIjAgBgNVBAMTGWNsb3VkLmFuZHJld3NvbWV0aGluZy5j\nb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDBIZMz8pnK6V52SVf+\nCYssOfCQHAx5f0Ou5rYbq3xNh8VWHIYJCQ1QxQIxKSP6+uODSYrb2KWyurP1DwGb\n8OYm0J3syEDtCUQik1cpCzpeNlAZ2f8FzXyYQAqPopxdRpsFz8DtZnVvu86XwrE4\noFPl9MReICmZfBNWylpV5qgFPoXyJ70ZAsTm3cEe3n+LBXEnY4YrVDRWxA3wZ2mz\nZ03HZ1hHrxK9CMnS829U+8sK+UneZpCO7yLRPuxwhmps0wpK/YuZZfRAKF1FZRna\nk/SIQ28rnWufmdg16YqqHgl5JOgnb3aslKRvL4dI2Gwnkd2IHtpZnTR0gxFXfqqb\nQwuRAgMBAAGjggIaMIICFjAOBgNVHQ8BAf8EBAMCBaAwHQYDVR0lBBYwFAYIKwYB\nBQUHAwEGCCsGAQUFBwMCMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFLsAFcxAhFX1\nMbCnzr9hEO5rL4jqMB8GA1UdIwQYMBaAFKhKamMEfd265tE5t6ZFZe/zqOyhMHAG\nCCsGAQUFBwEBBGQwYjAvBggrBgEFBQcwAYYjaHR0cDovL29jc3AuaW50LXgzLmxl\ndHNlbmNyeXB0Lm9yZy8wLwYIKwYBBQUHMAKGI2h0dHA6Ly9jZXJ0LmludC14My5s\nZXRzZW5jcnlwdC5vcmcvMCQGA1UdEQQdMBuCGWNsb3VkLmFuZHJld3NvbWV0aGlu\nZy5jb20wgf4GA1UdIASB9jCB8zAIBgZngQwBAgWrgeYGCysGAQQBgt8TAQEBMIHW\nMCYGCCsGAQUFBwIBFhpodHRwOi8vY3BzLmxldHNlbmNyeXB0Lm9yZzCBqwYIKwYB\nBQUHAgIwgZ4MgZtUaGlzIENlcnRpZmljYXRlIG1heSBvbmx5IGJlIHJlbGllZCB1\ncG9uIGJ5IFJlbHlpbmcgUGFydGllcyBhbmQgb25seSQ2ziBhY2NvcmRhbmNlIHdp\ndGggdGhlIENlcnRpZmljYXRlIFBvbGljeSBmb3VuZCBhdCBodHRwczovL2xldHNl\nbmNyeXB0Lm9yZy9yZXBvc2l0b3J5LzANBgkqhkiG9w0BAQsFAAOCAQEAOZVQvrjM\nPKXLARTjB5XsgfyDN3/qwLl7SmwGkPe+B+9FJpfScYG1JzVuCj/SoaPaK34G4x/e\niXwlwOXtMOtqjQYzNu2Pr2C+I+rVmaxIrCUXFmC205IMuUBEeWXG9Y/HvXQLPabD\nD3Gdl5+Feink9SDRP7G0HaAwq13hI7ARxkL9p+UIY39X0dV3WOboW2Re8nrkFXJ7\nq9Z6shK5QgpBfsLjtjNsQzaGV3ve1gOg25aTJGearBWOvEjJNA1wGMoKVXOtYwm/\nWyWoVdCQ8HmconcbJB6xc0UZ1EjvzRr5ZIvSa5uHZD0L3m7/kpPWlAlFJ7hHASPu\nUlF1zblDmg2Iaw==\n-----END CERTIFICATE-----"
+    description: Access certificate for TLS client authentication. (Kafka only)
+    readOnly: true
+
+  access_key:
+    type: string
+    example: "-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDBIZMz8pnK6V52\nSVf+CYssOfCQHAx5f0Ou5rYbq3xNh8VHAIYJCQ1QxQIxKSP6+uODSYrb2KWyurP1\nDwGb8OYm0J3syEDtCUQik1cpCzpeNlAZ2f8FzXyYQAqPopxdRpsFz8DtZnVvu86X\nwrE4oFPl9MReICmZfBNWylpV5qgFPoXyJ70ZAsTm3cEe3n+LBXEnY4YrVDRWxA3w\nZ2mzZ03HZ1hHrxK9CMnS829U+8sK+UneZpCO7yLRPuxwhmps0wpK/YuZZfRAKF1F\nZRnak/SIQ28rnWufmdg16YqqHgl5JOgnb3aslKRvL4dI2Gwnkd2IHtpZnTR0gxFX\nfqqbQwuRAgMBAAECggEBAILLmkW0JzOkmLTDNzR0giyRkLoIROqDpfLtjKdwm95l\n9NUBJcU4vCvXQITKt/NhtnNTexcowg8pInb0ksJpg3UGE+4oMNBXVi2UW5MQZ5cm\ncVkQqgXkBF2YAY8FMaB6EML+0En2+dGR/3gIAr221xsFiXe1kHbB8Nb2c/d5HpFt\neRpLVJnK+TxSr78PcZA8DDGlSgwvgimdAaFUNO2OqB9/0E9UPyKk2ycdff/Z6ldF\n0hkCLtdYTTl8Kf/OwjcuTgmA2O3Y8/CoQX/L+oP9Rvt9pWCEfuebiOmHJVPO6Y6x\ngtQVEXwmF1pDHH4Qtz/e6UZTdYeMl9G4aNO2CawwcaYECgYEA57imgSOG4XsJLRh\nGGncV9R/xhy4AbDWLtAMzQRX4ktvKCaHWyQV2XK2we/cu29NLv2Y89WmerTNPOU+\nP8+pB31uty2ELySVn15QhKpQClVEAlxCnnNjXYrii5LOM80+lVmxvQwxVd8Yz8nj\nIntyioXNBEnYS7V2RxxFGgFun1cCgYEA1V3W+Uyamhq8JS5EY0FhyGcXdHd70K49\nW1ou7McIpncf9tM9acLS1hkI98rd2T69Zo8mKoV1V2hjFaKUYfNys6tTkYWeZCcJ\n3rW44j9DTD+FmmjcX6b8DzfybGLehfNbCw6n67/r45DXIV/fk6XZfkx6IEGO4ODt\nNfnvx4TuI1cCgYBACDiKqwSUvmkUuweOo4IuCxyb5Ee8v98P5JIE/VRDxlCbKbpx\npxEam6aBBQVcDi+n8o0H3WjjlKc6UqbW/01YMoMrvzotxNBLz8Y0QtQHZvR6KoCG\nRKCKstxTcWflzKuknbqN4RapAhNbKBDJ8PMSWfyDWNyaXzSmBdvaidbF1QKBgDI0\no4oD0Xkjg1QIYAUu9FBQmb9JAjRnW36saNBEQS/SZg4RRKknM683MtoDvVIKJk0E\nsAlfX+4SXQZRPDMUMtA+Jyrd0xhj6zmhbwClvDMr20crF3fWdgcqtft1BEFmsuyW\nJUMe5OWmRkjPI2+9ncDPRAllA7a8lnSV/Crph5N/AoGBAIK249temKrGe9pmsmAo\nQbNuYSmwpnMoAqdHTrl70HEmK7ob6SIVmsR8QFAkH7xkYZc4Bxbx4h1bdpozGB+/\nAangbiaYJcAOD1QyfiFbflvI1RFeHgrk7VIafeSeQv6qu0LLMi2zUbpgVzxt78Wg\neTuK2xNR0PIM8OI7pRpgyj1I\n-----END PRIVATE KEY-----"
+    description: Access key for TLS client authentication. (Kafka only)
+    readOnly: true
+
   mysql_settings:
     $ref: './mysql_settings.yml'
 
+  settings:
+    $ref: './user_settings.yml'
+
 required:
   - name