FTL/src/api/docs/content/specs/dns.yaml

openapi: 3.0.2
components:
  paths:
    blocking:
      summary: Modify blocking
      get:
        summary: Get current blocking status
        tags:
          - DNS control
        operationId: "get_blocking"
        security:
          - sidHeader: []
        description: |
          The property `timer` may contain additional details concerning a temporary en-/disabling.
          It is `null` when no timer is active (the current status is permanent).
        responses:
          '200':
            description: OK
            content:
              application/json:
                schema:
                  allOf:
                    - $ref: '#/components/schemas/blocking'
                    - $ref: '#/components/schemas/timer'
      post:
        summary: Change current blocking status
        tags:
          - DNS control
        operationId: "set_blocking"
        description: |
          Change the current blocking mode by setting `blocking` to the desired value.
          The optional `timer` object may used to set a timer. Once this timer elapsed, the opposite blocking mode is automatically set.
          For instance, you can request `{blocking: true, timer: 60}` to disable Pi-hole for one minute.
          Blocking will be automatically resumed afterwards.

          You can terminate a possibly running timer by setting `timer` to `null` (the set mode becomes permanent).
        requestBody:
          description: Callback payload
          content:
            'application/json':
              schema:
                allOf:
                  - $ref: '#/components/schemas/blocking'
                  - $ref: '#/components/schemas/timer'
        responses:
          '200':
            description: OK
            content:
              application/json:
                schema:
                  allOf:
                    - $ref: '#/components/schemas/blocking'
                    - $ref: '#/components/schemas/timer'
          '400':
            description: Bad request
            content:
              application/json:
                schema:
                  oneOf:
                  - $ref: '#/components/schemas/errors/no_payload'
                  - $ref: '#/components/schemas/errors/item_missing'
          '401':
            description: Unauthorized
            content:
              application/json:
                schema:
                  $ref: 'common.yaml#/components/errors/unauthorized'
    cache:
      get:
        summary: Get cache info
        tags:
          - Metrics
        operationId: "get_cacheinfo"
        description: |
          This API hook returns live information about the DNS cache usage.
        responses:
          '200':
            description: OK
            content:
              application/json:
                schema:
                  allOf:
                    - $ref: '#/components/schemas/cache_size'
                    - $ref: '#/components/schemas/cache_inserted'
                    - $ref: '#/components/schemas/cache_evicted'
          '401':
            description: Unauthorized
            content:
              application/json:
                schema:
                  $ref: 'common.yaml#/components/errors/unauthorized'
    port:
      get:
        summary: Get DNS port
        tags:
          - Metrics
        operationId: "get_dns_port"
        description: |
          This API hook returns the DNS port currently used by Pi-hole.
        responses:
          '200':
            description: OK
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/dns_port'
  schemas:
    blocking:
      type: object
      properties:
        blocking:
          type: boolean
          description: Blocking status
          example: true
    timer:
      type: object
      properties:
        timer:
          type: integer
          description: Remaining seconds until blocking mode is automatically changed
          nullable: true
          example: 15
    cache_size:
      type: object
      properties:
        size:
          type: integer
          description: Size of the DNS domain cache
          example: 10000
    cache_inserted:
      type: object
      properties:
        inserted:
          type: integer
          description: Number of total insertions into the cache
          example: 100
    cache_evicted:
      type: object
      properties:
        evicted:
          type: integer
          description: The number of cache entries that had to be removed although the corresponding entries were **not** expired
          example: 0
    dns_port:
      type: object
      properties:
        dns_port:
          type: integer
          description: DNS port
          example: 53
    errors:
      item_missing:
        type: object
        description: Item to be modified is missing
        properties:
          error:
            type: object
            properties:
              key:
                type: string
                description: "Machine-readable error type"
                example: "body_error"
              message:
                type: string
                description: "Human-readable error message"
                example: "No \\\"blocking\\\" boolean in body data"
              hint:
                type: string
                nullable: true
                description: "Additional data (if available)"
                example: null
      no_payload:
        type: object
        description: No JSON payload found
        properties:
          error:
            type: object
            properties:
              key:
                type: string
                description: "Machine-readable error type"
                example: "bad_request"
              message:
                type: string
                description: "Human-readable error message"
                example: "Invalid request body data (no valid JSON)"
              hint:
                type: string
                nullable: true
                description: "Additional data (if available)"
                example: null