added api docs

interface/api/response/error.yaml

@@ -0,0 +1,19 @@
+components:
+  schemas:
+    ApiError:
+      type: object
+      additionalProperties: false
+      required:
+        - code
+        - error
+        - source
+      properties:
+        code:
+          type: integer
+          format: int32
+        error:
+          type: string
+        source:
+          type: string
+        details:
+          type: string

interface/api/response/operation.yaml

@@ -0,0 +1,78 @@
+components:
+  responses:
+    Ok:
+      description: Successful response
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/BaseResponse
+
+    Created:
+      description: Resource created
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/BaseResponse
+
+    Accepted:
+      description: Request accepted for processing
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/BaseResponse
+
+    BadRequest:
+      description: Bad request payload or query/path parameter
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/ErrorResponse
+
+    Unauthorized:
+      description: Unauthorized
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/ErrorResponse
+
+    Forbidden:
+      description: Forbidden
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/ErrorResponse
+
+    NotFound:
+      description: Resource not found
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/ErrorResponse
+
+    Gone:
+      description: Resource is no longer available
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/ErrorResponse
+
+    Conflict:
+      description: Conflict
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/ErrorResponse
+
+    TooManyRequests:
+      description: Too many requests
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/ErrorResponse
+
+    InternalServerError:
+      description: Internal server error
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/ErrorResponse

interface/api/response/response.yaml

@@ -0,0 +1,47 @@
+components:
+  schemas:
+    BaseResponse:
+      type: object
+      additionalProperties: false
+      required:
+        - status
+        - data
+      properties:
+        status:
+          $ref: ./status.yaml#/components/schemas/ApiStatus
+        data:
+          description: Payload for success or error responses.
+
+    ErrorResponse:
+      allOf:
+        - $ref: ./response.yaml#/components/schemas/BaseResponse
+        - type: object
+          properties:
+            status:
+              type: string
+              enum:
+                - error
+            data:
+              $ref: ./error.yaml#/components/schemas/ApiError
+
+    SuccessResultData:
+      type: object
+      additionalProperties: false
+      required:
+        - result
+      properties:
+        result:
+          type: boolean
+
+    SuccessResultResponse:
+      allOf:
+        - $ref: ./response.yaml#/components/schemas/BaseResponse
+        - type: object
+          properties:
+            status:
+              type: string
+              enum:
+                - success
+                - processed
+            data:
+              $ref: ./response.yaml#/components/schemas/SuccessResultData

interface/api/response/status.yaml

@@ -0,0 +1,10 @@
+components:
+  schemas:
+    ApiStatus:
+      type: string
+      description: Unified response status used by backend wrappers.
+      enum:
+        - success
+        - processed
+        - error
+        - request