external-dns/api/webhook.yaml

---
openapi: "3.0.0"
info:
  version: v0.15.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 Kubernetes 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: |
            Negociation failed.            

  /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'
              example:
                - dnsName: "test.example.com"
                  recordTTL: 10
                  recordType: 'A'
                  targets:
                    - "1.2.3.4"
        '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'
            example:
              create:
                - dnsName: "test.example.com"
                  recordTTL: 10
                  recordType: 'A'
      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'
            example:
              - dnsName: "test.example.com"
                recordTTL: 10
                recordType: 'A'
                targets:
                  - "1.2.3.4"
      responses:
        '200':
          description: |
            Adjustments were accepted.            
          content:
            application/external.dns.webhook+json;version=1:
              schema:
                $ref: '#/components/schemas/endpoints'
              example:
                - dnsName: "test.example.com"
                  recordTTL: 0
                  recordType: 'A'
                  targets:
                    - "1.2.3.4"
        '500':
          description: |
            Adjustments were not accepted.            

components:
  schemas:
    filters:
      description: |
        external-dns will only create DNS records for host names (specified in ingress objects and services with the external-dns annotation) related to zones that match filters. They can set in external-dns deployment manifest.        
      type: object
      properties:
        filters:
          type: array
          items:
            type: string
            example: "foo.example.com"
          example:
            - ".example.com"
      example:
        filters:
          - ".example.com"
          - ".example.org"

    endpoints:
      description: |
        This is a list of DNS records.        
      type: array
      items:
        $ref: '#/components/schemas/endpoint'
      example:
        - dnsName: foo.example.com
          recordType: A
          recordTTL: 60

    endpoint:
      description: |
        This is a DNS record.        
      type: object
      properties:
        dnsName:
          type: string
          example: "foo.example.org"
        targets:
          $ref: '#/components/schemas/targets'
        recordType:
          type: string
          example: "CNAME"
        setIdentifier:
          type: string
          example: "v1"
        recordTTL:
          type: integer
          format: int64
          example: 60
        labels:
          type: object
          additionalProperties:
            type: string
            example: "foo"
          example:
            foo: bar
        providerSpecific:
          type: array
          items:
            $ref: '#/components/schemas/providerSpecificProperty'
          example:
            - name: foo
              value: bar
      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"
      example:
        - "1.2.3.4"
        - "test.example.org"

    providerSpecificProperty:
      description: |
        Allows provider to pass property specific to their implementation.        
      type: object
      properties:
        name:
          type: string
          example: foo
        value:
          type: string
          example: bar
      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'
      example:
        create:
          - dnsName: foo.example.com
            recordType: A
            recordTTL: 60
        delete:
          - dnsName: foo.example.org
            recordType: CNAME