openapi: "3.0.0"
info:
  description: "Simple dynDNS via Rest-API."
  version: "1.0"
  title: "rynDNS"

servers:
  - url: "https://api.pdev.dev/rynDNS/v1"
    description: ""

security:
  - api_key: []

paths:
  /admin/client:
    post:
      tags:
        - "admin"
      summary: "Create or update a client and retrieve a new API key"
      description: ""
      operationId: "create_client"
      parameters:
        - $ref: "#/components/parameters/api_key"
      requestBody:
        description: "An existing clients properties wil only be updated if the parameter is present."
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/client"
      responses:
        "200":
          description: "Client updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/admin_client_api_key"
        "201":
          description: "Client created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/admin_client_api_key"
        "401":
          $ref: "#/components/responses/unauthorized"
        "403":
          $ref: "#/components/responses/forbidden"
        "405":
          description: "Invalid input"
        "406":
          description: "Not Acceptable - Can not remove last admin account permissions"
    put:
      tags:
        - "admin"
      summary: "Update an existing client"
      description: ""
      operationId: "update_client"
      parameters:
        - $ref: "#/components/parameters/api_key"
      requestBody:
        description: "An existing clients properties wil only be updated if the parameter is present."
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/client"
      responses:
        "200":
          description: "Client updated"
        "401":
          $ref: "#/components/responses/unauthorized"
        "403":
          $ref: "#/components/responses/forbidden"
        "404":
          $ref: "#/components/responses/not_found"
        "405":
          description: "Invalid input"
        "406":
          description: "Not Acceptable - Can not remove last admin account permissions"
  /admin/clients:
    get:
      tags:
        - "admin"
      summary: "Retrieve all clients information"
      description: ""
      operationId: "get_all_client"
      parameters:
        - $ref: "#/components/parameters/api_key"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/admin_client_info_array"
        "401":
          $ref: "#/components/responses/unauthorized"
        "403":
          $ref: "#/components/responses/forbidden"
  /admin/clients/{client_name}:
    parameters:
      - $ref: "#/components/parameters/api_key"
      - $ref: "#/components/parameters/client_name"
    get:
      tags:
        - "admin"
      summary: "Retrieve client information"
      description: ""
      operationId: "get_client"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/admin_client_info"
        "401":
          $ref: "#/components/responses/unauthorized"
        "403":
          $ref: "#/components/responses/forbidden"
        "404":
          $ref: "#/components/responses/not_found"
    delete:
      tags:
        - "admin"
      summary: "Delete an existing client"
      description: ""
      operationId: "delete_client"
      responses:
        "200":
          description: "Client deleted"
        "401":
          $ref: "#/components/responses/unauthorized"
        "403":
          $ref: "#/components/responses/forbidden"
        "404":
          $ref: "#/components/responses/not_found"
        "406":
          description: "Not Acceptable - Can not delete last admin account"

  /client:
    parameters:
      - $ref: "#/components/parameters/api_key"
    put:
      tags:
        - "client (write)"
      summary: "Update ipv4 client information based on request IP or body if present"
      description: "If body is present, it will take precedence over the request IP. Response contains the newly set `ipv4` value."
      operationId: "update_client_ip"
      requestBody:
        description: "An existing clients properties wil only be updated if the parameter is present."
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/client_update"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/client_info"
        "401":
          $ref: "#/components/responses/unauthorized"
        "403":
          $ref: "#/components/responses/forbidden"
        "406":
          description: "Not Acceptable - IPv4 Address is invalid"
    delete:
      tags:
        - "client (write)"
      summary: "Delete an existing ipv4 client information"
      description: "Response contains the previously set `ipv4` value before deletion."
      operationId: "delete_client_ip"
      responses:
        "200":
          description: "IP deleted"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/client_info"
        "401":
          $ref: "#/components/responses/unauthorized"
        "403":
          $ref: "#/components/responses/forbidden"

  /clients/{client_name}:
    parameters:
      - $ref: "#/components/parameters/api_key"
      - $ref: "#/components/parameters/client_name"
    get:
      tags:
        - "client (read)"
      summary: "Get ipv4 client information"
      description: ""
      operationId: "get_client_ip"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/client_info"
        "401":
          $ref: "#/components/responses/unauthorized"
        "403":
          $ref: "#/components/responses/forbidden"
        "404":
          $ref: "#/components/responses/not_found"

  /public/{client_name}:
    parameters:
      - $ref: "#/components/parameters/client_name"
    get:
      tags:
        - "public"
      summary: "Get ipv4 client information"
      description: ""
      operationId: "get_public_client_ip"
      security: []
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/client_info"
        "401":
          $ref: "#/components/responses/unauthorized_public"

components:

  # security
  securitySchemes:
    api_key:
      in: "header"
      type: "apiKey"
      name: "X-API-Key"

  # parameters
  parameters:
    api_key:
      in: "header"
      name: "X-API-Key"
      required: true
      schema:
        type: "string"
    client_name:
      in: "path"
      name: "client_name"
      required: true
      schema:
        $ref: "#/components/schemas/client_name"

  # responses:
  responses:
    ## 401
    unauthorized:
      description: "Unauthorized - api_key must be present in Header"
    unauthorized_public:
      description: "Unauthorized - Ressource is not public"
    ## 403
    forbidden:
      description: "Forbidden - api_key not unauthorized"
    ## 404
    not_found:
      description: "Client not found"

  # schemas:
  schemas:
    # objects
    client:
      type: "object"
      required:
        - "name"
      properties:
        name:
          $ref: "#/components/schemas/client_name"
        description:
          $ref: "#/components/schemas/client_description"
        permission:
          $ref: "#/components/schemas/client_permission"
        public_ip:
          $ref: "#/components/schemas/client_public"
    admin_client_api_key:
      type: "object"
      properties:
        name:
          $ref: "#/components/schemas/client_name"
        api_key:
          $ref: "#/components/schemas/client_api_key"
    admin_client_info_array:
      type: "array"
      items:
        $ref: "#/components/schemas/admin_client_info"
    admin_client_info:
      type: "object"
      properties:
        name:
          $ref: "#/components/schemas/client_name"
        description:
          $ref: "#/components/schemas/client_description"
        permission:
          $ref: "#/components/schemas/client_permission"
        public_ip:
          $ref: "#/components/schemas/client_public"
        ipv4:
          $ref: "#/components/schemas/client_ipv4"
    client_info:
      type: "object"
      properties:
        name:
          $ref: "#/components/schemas/client_name"
        ipv4:
          $ref: "#/components/schemas/client_ipv4"
    client_update:
      type: "object"
      properties:
        ipv4:
          $ref: "#/components/schemas/client_ipv4"
    # vars
    client_name:
      type: "string"
      minLength: 3
      maxLength: 20
      example: "clientA"
      description: "Unique client identifier"
    client_permission:
      type: "string"
      example: "rw"
      pattern: "^r?w?x?$"
      description: |
        Set permission of client.
        `r`: `client (read)` access
        `w`: `client (write)` access
        `x`: `admin` access
        *default: w*
    client_description:
      type: "string"
      maxLength: 200
      example: "Client across the river"
      description: "default: ''"
    client_public:
      type: "boolean"
      example: "false"
      description: |
        Set `true` to enable public read access
        *default: false*
    client_api_key:
      type: "string"
      example: "kakJwkejfiJkadkjhou35oi902ijsfli"
    client_ipv4:
      type: "string"
      format: "ipv4"
      example: "115.16.0.99"
      pattern: "^(((25[0-5]|(2[0-4]|1[0-9]|[1-9]|)[0-9])(.(?!$)|$)){4})?$"
externalDocs:
  description: "Source"
  url: "https://git.pdev.dev"