feat: initial OpenAPI spec for webhook provider

.github/workflows/lint.yaml

@@ -33,3 +33,13 @@ jobs:
       run: |
         curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.55.2
         make lint
+
+    - name: Install Vacuum
+      # See: https://quobix.com/vacuum/installing/
+      run: |
+        curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh > /dev/null
+      shell: bash
+    - name: Run Vacuum
+      run: |
+        vacuum lint -d api/webhook.yaml
+      shell: bash

api/webhook.yaml

@@ -0,0 +1,214 @@
+---
+openapi: "3.0.0"
+info:
+  version: 0.14.0
+  title: External DNS Webhook Server
+  description: >-
+    Implements the external DNS webhook endpoints.
+  contact:
+    url: https://github.com/kubernetes-sigs/external-dns
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+tags:
+  - name: initialization
+    description: Endpoints for initial negotiation.
+  - name: listing
+    description: Endpoints to get listings of DNS records.
+  - name: update
+    description: Endpoints to update DNS records.
+servers:
+  - url: http://localhost:8888
+    description: Server url for a k8s deployment.
+paths:
+  /:
+    get:
+      summary: >-
+        Initialisation and negotiates headers and returns domain
+        filter.
+      description: |
+        Initialisation and negotiates headers and returns domain
+        filter.
+      operationId: negotiate
+      tags: [initialization]
+      responses:
+        '200':
+          description: |
+            The list of domains this DNS provider serves.
+          content:
+            application/external.dns.webhook+json;version=1:
+              schema:
+                $ref: '#/components/schemas/filters'
+              example:
+                filters:
+                  - example.com
+        '500':
+          description: |
+            Failed to provide the list of domains we serve.
+
+  /records:
+    get:
+      summary: Returns the current records.
+      description: |
+        Get the current records from the DNS provider and return them.
+      operationId: getRecords
+      tags: [listing]
+      responses:
+        '200':
+          description: |
+            Provided the list of DNS records successfully.
+          content:
+            application/external.dns.webhook+json;version=1:
+              schema:
+                $ref: '#/components/schemas/endpoints'
+        '500':
+          description: |
+            Failed to provide the list of DNS records.
+
+    post:
+      summary: Applies the changes.
+      description: |
+        Set the records in the DNS provider based on those supplied here.
+      operationId: setRecords
+      tags: [update]
+      requestBody:
+        description: |
+          This is the list of changes that need to be applied.  There are
+          four lists of endpoints.  The `create` and `delete` lists are lists
+          of records to create and delete respectively.  The `updateOld` and
+          `updateNew` lists are paired.  For each entry there's the old version
+          of the record and a new version of the record.
+        required: true
+        content:
+          application/external.dns.webhook+json;version=1:
+            schema:
+              $ref: '#/components/schemas/changes'
+      responses:
+        '204':
+          description: |
+            Changes were accepted.
+        '500':
+          description: |
+            Changes were not accepted.
+
+  /adjustendpoints:
+    post:
+      summary: Executes the AdjustEndpoints method.
+      description: |
+        Adjusts the records in the provider based on those supplied here.
+      operationId: adjustRecords
+      tags: [update]
+      requestBody:
+        description: |
+          This is the list of changes to be applied.
+        required: true
+        content:
+          application/external.dns.webhook+json;version=1:
+            schema:
+              $ref: '#/components/schemas/endpoints'
+      responses:
+        '200':
+          description: |
+            Adjustments were accepted.
+          content:
+            application/external.dns.webhook+json;version=1:
+              schema:
+                $ref: '#/components/schemas/endpoints'
+        '500':
+          description: |
+            Adjustments were not accepted.
+
+components:
+  schemas:
+    filters:
+      description: |
+        TODO: explain the filters object.
+      type: object
+      properties:
+        filters:
+          type: array
+          items:
+            type: string
+      example:
+        filters:
+          - foo.example.com
+
+    endpoints:
+      description: |
+        This is a list of DNS records.
+      type: array
+      items:
+        $ref: '#/components/schemas/endpoint'
+
+    endpoint:
+      description: |
+        This is a DNS record.
+      type: object
+      properties:
+        dnsName:
+          type: string
+        targets:
+          $ref: '#/components/schemas/targets'
+        recordType:
+          type: string
+        setIdentifier:
+          type: string
+        recordTTL:
+          type: integer
+          format: int64
+        labels:
+          type: object
+          additionalProperties:
+            type: string
+        providerSpecific:
+          type: array
+          items:
+            $ref: '#/components/schemas/providerSpecificProperty'
+      example:
+        dnsName: foo.example.com
+        recordType: A
+        recordTTL: 60
+
+    targets:
+      description: |
+        This is the list of targets that this DNS record points to.
+        So for an A record it will be a list of IP addresses.
+      type: array
+      items:
+        type: string
+      example:
+        - 1.2.3.4
+        - 1.2.3.5
+
+    providerSpecificProperty:
+      description: |
+        TODO: explain the provider object.  What might this be used for?
+        Examples?
+      type: object
+      properties:
+        name:
+          type: string
+        value:
+          type: string
+      example:
+        name: foo
+        value: bar
+
+    changes:
+      description: |
+        This is the list of changes send by `external-dns` that need to
+        be applied.  There are four lists of endpoints.  The `create`
+        and `delete` lists are lists of records to create and delete
+        respectively.  The `updateOld` and `updateNew` lists are paired.
+        For each entry there's the old version of the record and a new
+        version of the record.
+      type: object
+      properties:
+        create:
+          $ref: '#/components/schemas/endpoints'
+        updateOld:
+          $ref: '#/components/schemas/endpoints'
+        updateNew:
+          $ref: '#/components/schemas/endpoints'
+        delete:
+          $ref: '#/components/schemas/endpoints'