insforge 0.3.1

package/openapi/records.yaml

@@ -0,0 +1,382 @@
+openapi: 3.0.3
+info:
+  title: Insforge Records API
+  version: 2.0.0
+  description: PostgREST-style database record operations
+
+paths:
+  /api/database/records/{tableName}:
+    get:
+      summary: Query Records
+      description: Query records from a table with filtering, sorting, and pagination
+      tags:
+        - Client
+      security:
+        - bearerAuth: []
+        - apiKey: []
+      parameters:
+        - name: tableName
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Name of the table to query
+          example: users
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 100
+            minimum: 1
+            maximum: 1000
+          description: Maximum number of records to return
+        - name: offset
+          in: query
+          schema:
+            type: integer
+            default: 0
+            minimum: 0
+          description: Number of records to skip for pagination
+        - name: order
+          in: query
+          schema:
+            type: string
+          description: Sort order (e.g., "createdAt.desc", "name.asc")
+          example: createdAt.desc
+        - name: select
+          in: query
+          schema:
+            type: string
+          description: Comma-separated list of columns to return
+          example: id,name,email
+        # PostgREST-style filters
+        - name: field
+          in: query
+          schema:
+            type: string
+          description: Filter by field value (e.g., "?status=eq.active", "?age=gt.18")
+          example: status=eq.active
+      responses:
+        '200':
+          description: List of records
+          headers:
+            X-Total-Count:
+              schema:
+                type: integer
+              description: Total number of records matching the query
+            Content-Range:
+              schema:
+                type: string
+              description: Range of records returned (e.g., "0-99/1234")
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  additionalProperties: true
+              example:
+                - id: "248373e1-0aea-45ce-8844-5ef259203749"
+                  name: "John Doe"
+                  email: "john@example.com"
+                  createdAt: "2025-07-18T05:37:24.338Z"
+                  updatedAt: "2025-07-18T05:37:24.338Z"
+                - id: "348373e1-0aea-45ce-8844-5ef259203750"
+                  name: "Jane Smith"
+                  email: "jane@example.com"
+                  createdAt: "2025-07-19T08:15:10.123Z"
+                  updatedAt: "2025-07-19T08:15:10.123Z"
+        '404':
+          description: Table not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              example:
+                error: "TABLE_NOT_FOUND"
+                message: "Table 'nonexistent' does not exist"
+                statusCode: 404
+                nextActions: "Check table name and try again"
+        '400':
+          description: Invalid query parameters
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              example:
+                error: "INVALID_QUERY"
+                message: "Invalid filter syntax"
+                statusCode: 400
+                nextActions: "Check PostgREST filter documentation"
+
+    post:
+      summary: Create Records
+      description: Create one or more records. Request body MUST be an array.
+      tags:
+        - Client
+      security:
+        - bearerAuth: []
+        - apiKey: []
+      parameters:
+        - name: tableName
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Name of the table
+          example: users
+        - name: Prefer
+          in: header
+          schema:
+            type: string
+            enum: ["return=representation"]
+          description: Include to return created records in response (otherwise returns empty array)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                type: object
+                additionalProperties: true
+              minItems: 1
+            example:
+              - name: "John Doe"
+                email: "john@example.com"
+                age: 30
+      responses:
+        '201':
+          description: Records created
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  additionalProperties: true
+              examples:
+                without_prefer:
+                  summary: Response without Prefer header
+                  value: []
+                with_prefer:
+                  summary: "Response with Prefer: return=representation"
+                  value:
+                    - id: "248373e1-0aea-45ce-8844-5ef259203749"
+                      name: "John Doe"
+                      email: "john@example.com"
+                      age: 30
+                      createdAt: "2025-07-18T05:37:24.338Z"
+                      updatedAt: "2025-07-18T05:37:24.338Z"
+        '400':
+          description: Invalid input
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              example:
+                error: "VALIDATION_ERROR"
+                message: "Invalid field type: expected integer for 'age'"
+                statusCode: 400
+                nextActions: "Ensure field types match the table schema"
+        '404':
+          description: Table not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              example:
+                error: "TABLE_NOT_FOUND"
+                message: "Table 'nonexistent' does not exist"
+                statusCode: 404
+                nextActions: "Create the table first"
+
+    patch:
+      summary: Update Records
+      description: Update records matching query filters
+      tags:
+        - Client
+      security:
+        - bearerAuth: []
+        - apiKey: []
+      parameters:
+        - name: tableName
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Name of the table
+          example: users
+        - name: id
+          in: query
+          schema:
+            type: string
+          description: Filter records by ID (e.g., "?id=eq.123e4567-e89b-12d3-a456-426614174000")
+          example: eq.123e4567-e89b-12d3-a456-426614174000
+        - name: Prefer
+          in: header
+          schema:
+            type: string
+            enum: ["return=representation"]
+          description: Include to return updated records in response
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: true
+            example:
+              name: "Jane Doe"
+              email: "jane.doe@example.com"
+      responses:
+        '200':
+          description: Records updated
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  additionalProperties: true
+              examples:
+                without_prefer:
+                  summary: Response without Prefer header
+                  value: []
+                with_prefer:
+                  summary: "Response with Prefer: return=representation"
+                  value:
+                    - id: "123e4567-e89b-12d3-a456-426614174000"
+                      name: "Jane Doe"
+                      email: "jane.doe@example.com"
+                      createdAt: "2025-01-01T00:00:00Z"
+                      updatedAt: "2025-01-21T11:00:00Z"
+        '404':
+          description: No records found to update
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+              example: []
+        '400':
+          description: Invalid input
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              example:
+                error: "VALIDATION_ERROR"
+                message: "Invalid field type"
+                statusCode: 400
+                nextActions: "Check field types match table schema"
+
+    delete:
+      summary: Delete Records
+      description: Delete records matching query filters
+      tags:
+        - Client
+      security:
+        - bearerAuth: []
+        - apiKey: []
+      parameters:
+        - name: tableName
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Name of the table
+          example: users
+        - name: id
+          in: query
+          schema:
+            type: string
+          description: Filter records by ID (e.g., "?id=eq.123e4567-e89b-12d3-a456-426614174000")
+          example: eq.123e4567-e89b-12d3-a456-426614174000
+        - name: Prefer
+          in: header
+          schema:
+            type: string
+            enum: ["return=representation"]
+          description: Include to return deleted records in response
+      responses:
+        '204':
+          description: Records deleted (without Prefer header)
+        '200':
+          description: Records deleted (with Prefer header)
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  additionalProperties: true
+              examples:
+                records_deleted:
+                  summary: Records were deleted
+                  value:
+                    - id: "123e4567-e89b-12d3-a456-426614174000"
+                      name: "Deleted User"
+                      createdAt: "2025-01-01T00:00:00Z"
+                      updatedAt: "2025-01-21T11:00:00Z"
+                no_records:
+                  summary: No records found to delete
+                  value: []
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+    apiKey:
+      type: apiKey
+      in: header
+      name: x-api-key
+
+  schemas:
+    ErrorResponse:
+      type: object
+      required:
+        - error
+        - message
+        - statusCode
+      properties:
+        error:
+          type: string
+          description: Error code for programmatic handling
+          example: "VALIDATION_ERROR"
+        message:
+          type: string
+          description: Human-readable error message
+          example: "Invalid input data"
+        statusCode:
+          type: integer
+          description: HTTP status code
+          example: 400
+        nextActions:
+          type: string
+          description: Suggested action to resolve the error
+          example: "Check the request body format"
+
+    Record:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Auto-generated UUID
+        createdAt:
+          type: string
+          format: date-time
+          description: Timestamp when record was created
+        updatedAt:
+          type: string
+          format: date-time
+          description: Timestamp when record was last updated
+      additionalProperties: true
+      description: Base record structure with system fields
+
+security:
+  - bearerAuth: []
+  - apiKey: []