OpenAPI document for a webhook provider

[lyda]

What would you like to be added: I'd like an OpenAPI document to reflect how webhooks should be implemented. The documentation on this is a bit out of date so generating the webhook client in this project via the OpenAPI document and having server boilerplate provided means that projects could either include the webhook server from here or base their server off the OpenAPI doc here.

Why is this needed: To fully take advantage of #3063 it seems like it would be easier if webhook implementations were easier to do.

Based on reading the docs and the code, the OpenAPI doc for the webhook server would seem to be this. Is this correct?

---
openapi: "3.0.0"
info:
  version: 1.0.0
  title: External DNS Webhook Server
  description: >-
    Implements the external DNS webhook endpoints.
  contact:
    name: Author Name
    email: author@email.tld
    url: https://author.website.tld/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
paths:
  /healthz:
    get:
      summary: Health check
      description: Used by kubernetes to make sure service is ok.
      operationId: healthz
      responses:
        '200':
          description: Positive response
          content:
            text/plain:
              schema:
                type: string
                example: ok

  /:
    get:
      summary: >-
        Initialisation and negotiates headers and returns domain
        filter.
      description: |
        Initialisation and negotiates headers and returns domain
        filter.
      operationId: negotiate
      responses:
        '200':
          description: Positive response
          content:
            application/external.dns.webhook+json;version=1:
              schema:
                type: object
                properties:
                  filters:
                    type: array
                    items:
                      type: string
        '500':
          description: Failure

  /records:
    get:
      summary: Returns the current records.
      description: Get the current records from OpenWRT and return them.
      operationId: getRecords
      responses:
        '200':
          description: Positive response
          content:
            application/external.dns.webhook+json;version=1:
              schema:
                $ref: '#/components/schemas/endpoints'
        '500':
          description: Failure

    post:
      summary: Applies the changes.
      description: Set the records in OpenWRT based on those supplied here.
      operationId: setRecords
      requestBody:
        required: true
        content:
          application/external.dns.webhook+json;version=1:
            schema:
              $ref: '#/components/schemas/changes'
      responses:
        '204':
          description: Positive response
        '500':
          description: Failure

  /adjustendpoints:

    post:
      summary: Executes the AdjustEndpoints method.
      description: Set the records in OpenWRT based on those supplied here.
      operationId: adjustRecords
      requestBody:
        required: true
        content:
          application/external.dns.webhook+json;version=1:
            schema:
              $ref: '#/components/schemas/endpoints'
      responses:
        '200':
          description: Positive response
          content:
            application/external.dns.webhook+json;version=1:
              schema:
                $ref: '#/components/schemas/endpoints'
        '500':
          description: Failure

components:
  schemas:
    endpoints:
      type: array
      items:
        type: object
        properties:
          dnsName:
            type: string
          targets:
            type: string
          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'

    providerSpecificProperty:
      type: object
      properties:
        name:
          type: string
        value:
          type: string

    changes:
      type: object
      properties:
        create:
          $ref: '#/components/schemas/endpoints'
        updateOld:
          $ref: '#/components/schemas/endpoints'
        updateNew:
          $ref: '#/components/schemas/endpoints'
        delete:
          $ref: '#/components/schemas/endpoints'

[Raffo]

You are right, this is a totally valid addition. At some point I was investigating if it was possible to generate it from code, but it looks like it isn't possible. I haven't fully looked at this as I'm from mobile but I'd be happy to review a PR that adds the correct yaml which should be fairly trivial to write. I would leave out the health route though as that is intended for kubernetes and is not part of the spec for the webhook .

[lyda]

I can make a PR. It is possible to generate from the doc. I can provide a separate PR for that.

…

On Thu 28 Dec 2023, 11:58 Raffaele Di Fazio, ***@***.***> wrote: You are right, this is a totally valid addition. At some point I was investigating if it was possible to generate it from code, but it looks like it isn't possible. I haven't fully looked at this as I'm from mobile but I'd be happy to review a PR that adds the correct yaml which should be fairly trivial to write. I would leave out the health route though as that is intended for kubernetes and is not part of the spec for the webhook . — Reply to this email directly, view it on GitHub <#4138 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFOLDBXE75J77KY725NYXLYLVNGHAVCNFSM6AAAAABBDN2PS2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQNZRGA4TSMBUG4> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[augeivv]

I think a better documentation for the webhooks is urgently needed, so thanks for the OpenAPI Spec.
What is the difference between post of /records and /adjustendpoints?

[readonlyden]

Yeah, I'm trying to develop a webhook provider for our local DNS service and it's a pain due to lack of the documenation. Thanks for this OpenAPI spec.

As I see, targets property should be a string[] type, not just a string property.

[lyda]

I think a better documentation for the webhooks is urgently needed, so thanks for the OpenAPI Spec. What is the difference between post of /records and /adjustendpoints?

I'm trying to figure that out. Life keeps interrupting but I was going to review the client code in external-dns and some existing webhook servers to see what they do.

[augeivv]

Hello, I have figured it out myself in the meantime. /adjustendpoints is for customizing the records according to the requirements of the respective provider. /records is for applying the changes.

I am currently in the process of implementing a webhook myself. And I'm having to wade through the poor documentation....

[lyda]

Sadly I'm in the middle of a power outage so can't participate at the moment. Could you share the URL to your project? I'm going through all the webhook servers to see what they do. Thanks!

…

On Mon 22 Jan 2024, 07:54 augeivv, ***@***.***> wrote: Hello, I have figured it out myself in the meantime. /adjustendpoints is for customizing the records according to the requirements of the respective provider. /records is for applying the changes. I am currently in the process of implementing a webhook myself. And I'm having to wade through the poor documentation.... — Reply to this email directly, view it on GitHub <#4138 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFOLDCYTG4OL4GL4ENTFD3YPYLLJAVCNFSM6AAAAABBDN2PS2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSMBTGQZTKMJUHA> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[augeivv]

Unfortunately, this is not yet possible. On the one hand, I am not yet ready to show anything. On the other hand, the project is in the company network and is not publicly accessible.

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle rotten
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Reopen this issue with /reopen
• Mark this issue as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close not-planned

[k8s-ci-robot]

@k8s-triage-robot: Closing this issue, marking it as "Not Planned".

In response to this:

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Reopen this issue with /reopen
• Mark this issue as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close not-planned

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.