[add] initial commit

api.yml

@@ -0,0 +1,360 @@
+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"