Refactored capabilities into info endpoint

openapi.yml

@@ -1,5 +1,5 @@
 openapi: 3.1.0
 info:
   title: µEd API - Educational Microservices
   version: 0.1.0
   contact:
@@ -22,9 +22,13 @@
 paths:
   /evaluate:
     $ref: "./paths/evaluate/evaluate.yml"
+  /evaluate/info:
+    $ref: "./paths/evaluate/evaluate-info.yml"
   /evaluate/health:
     $ref: "./paths/evaluate/evaluate-health.yml"
   /chat:
     $ref: "./paths/chat/chat.yml"
+  /chat/info:
+    $ref: "./paths/chat/chat-info.yml"
   /chat/health:
     $ref: "./paths/chat/chat-health.yml"

paths/chat/chat-health.yml

@@ -1,18 +1,17 @@
 get:
-  summary: Health and capabilities of the chat service
+  summary: Health of the chat service
   operationId: getChatHealth
   description: >
-    Returns health information and capabilities of the chat service.
-    Clients can use this endpoint to discover whether the service supports
-    optional features such as user preferences or streaming responses.
+    Returns health of the chat service.
+    Clients can use this endpoint to discover whether the service is healthy
   tags:
     - chat
   parameters:
     - $ref: "../shared/parameters/X-Request-Id.yml"
     - $ref: "../shared/parameters/X-Api-Version.yml"
   responses:
     "200":
-      description: Chat service is reachable and reporting capabilities.
+      description: Chat service is reachable and reporting healthy.
       headers:
         X-Request-Id:
           description: Request id for tracing this request across services.
@@ -33,19 +32,6 @@ get:
                 status: "OK"
                 statusMessage: "Service healthy"
                 version: "1.0.0"
-                capabilities:
-                  supportsChat: true
-                  supportsUserPreferences: true
-                  supportsStreaming: true
-                  "supportsDataPolicy": "NOT_SUPPORTED"
-                  supportedLanguages:
-                    - "en"
-                    - "de"
-                  supportedModels:
-                    - "gpt-4o"
-                    - "llama-3"
-                  supportedVersions:
-                    - "0.1.0"
     "406":
       $ref: "./responses/406-VersionNotSupported.yml"
     "501":

paths/chat/chat-info.yml

@@ -0,0 +1,51 @@
+get:
+  summary: Information of the chat service
+  operationId: getChatInfo
+  description: >
+    Returns information and capabilities of the chat service.
+    Clients can use this endpoint to discover whether the service supports
+    optional features such as user preferences or streaming responses.
+  tags:
+    - chat
+  parameters:
+    - $ref: "../shared/parameters/X-Request-Id.yml"
+    - $ref: "../shared/parameters/X-Api-Version.yml"
+  responses:
+    "200":
+      description: Chat service is reachable and reporting capabilities.
+      headers:
+        X-Request-Id:
+          description: Request id for tracing this request across services.
+          schema:
+            type: string
+        X-Api-Version:
+          description: The API version that was used to serve this response.
+          schema:
+            type: string
+      content:
+        application/json:
+          schema:
+            $ref: "./schemas/ChatInfoResponse.yml"
+          examples:
+            exampleInfo:
+              summary: Example service with capabilities
+              value:
+                version: "1.0.0"
+                capabilities:
+                  supportsChat: true
+                  supportsUserPreferences: true
+                  supportsStreaming: true
+                  "supportsDataPolicy": "NOT_SUPPORTED"
+                  supportedLanguages:
+                    - "en"
+                    - "de"
+                  supportedModels:
+                    - "gpt-4o"
+                    - "llama-3"
+                  supportedVersions:
+                    - "0.1.0"
+    "406":
+      $ref: "./responses/406-VersionNotSupported.yml"
+    "501":
+      description: The server does not implement the info endpoint for chat.
+      $ref: "./responses/501-NotImplemented.yml"

paths/chat/schemas/ChatHealthResponse.yml

@@ -1,8 +1,7 @@
 type: object
-description: Health status and capabilities of the chat service.
+description: Health status of the chat service.
 required:
   - status
-  - capabilities
 properties:
   status:
     $ref: "../../shared/enums/HealthStatus.yml"
@@ -16,5 +15,3 @@ properties:
       - string
       - "null"
     description: Optional version of the chat service implementation.
-  capabilities:
-    $ref: "./ChatCapabilities.yml"

paths/chat/schemas/ChatInfoResponse.yml

@@ -0,0 +1,12 @@
+type: object
+description: Information and capabilities of the chat service.
+required:
+  - capabilities
+properties:
+  version:
+    type:
+      - string
+      - "null"
+    description: Optional version of the chat service implementation.
+  capabilities:
+    $ref: "./ChatCapabilities.yml"

paths/evaluate/evaluate-health.yml

@@ -1,11 +1,8 @@
 get:
-  summary: Health and capabilities of the evaluate service
+  summary: Health of the evaluate service
   operationId: getEvaluateHealth
   description: >
-    Returns health information and capabilities of the evaluate service.
-    Clients can use this endpoint to discover whether the service supports
-    optional features such as pre-submission feedback, formative feedback,
-    and summative feedback.
+    Returns health information of the evaluate service.
   tags:
     - evaluate
   parameters:
@@ -34,22 +31,6 @@ get:
                 status: "OK"
                 message: "Service healthy"
                 version: "1.0.0"
-                capabilities:
-                  supportsEvaluate: true
-                  supportsPreSubmissionFeedback: false
-                  supportsFormativeFeedback: true
-                  supportsSummativeFeedback: true
-                  supportsDataPolicy: "PARTIAL"
-                  supportedArtefactProfiles:
-                    - supportedFormats: ["text:plain", "text:markdown"]
-                    - supportedFormats:
-                        ["code:python", "code:java", "code:javascript"]
-                    - supportedFormats: ["math:latex", "math:mathml"]
-                  supportedLanguages:
-                    - "en"
-                    - "de"
-                  supportedVersions:
-                    - "0.1.0"
     "406":
       $ref: "./responses/406-VersionNotSupported.yml"
     "501":

paths/evaluate/evaluate-info.yml

@@ -0,0 +1,57 @@
+get:
+  summary: Information and capabilities of the evaluate service
+  operationId: getEvaluateInfo
+  description: >
+    Returns information and capabilities of the evaluate service.
+    Clients can use this endpoint to discover whether the service supports
+    optional features such as pre-submission feedback, formative feedback,
+    and summative feedback.
+  tags:
+    - evaluate
+  parameters:
+    - $ref: "../shared/parameters/X-Request-Id.yml"
+    - $ref: "../shared/parameters/X-Api-Version.yml"
+  responses:
+    "200":
+      description: Evaluate service is reachable and reporting capabilities.
+      headers:
+        X-Request-Id:
+          description: Request id for tracing this request across services.
+          schema:
+            type: string
+        X-Api-Version:
+          description: The API version that was used to serve this response.
+          schema:
+            type: string
+      content:
+        application/json:
+          schema:
+            $ref: "./schemas/EvaluateInfoResponse.yml"
+          examples:
+            exampleInfo:
+              summary: Example service with capabilities
+              value:
+                version: "1.0.0"
+                capabilities:
+                  supportsEvaluate: true
+                  supportsPreSubmissionFeedback: false
+                  supportsFormativeFeedback: true
+                  supportsSummativeFeedback: true
+                  supportsDataPolicy: "PARTIAL"
+                  supportedArtefactProfiles:
+                    - type: "TEXT"
+                      supportedFormats: ["plain", "markdown"]
+                    - type: "CODE"
+                      supportedFormats: ["python", "java", "javascript"]
+                    - type: "MATH"
+                      supportedFormats: ["latex", "mathml"]
+                  supportedLanguages:
+                    - "en"
+                    - "de"
+                  supportedVersions:
+                    - "0.1.0"
+    "406":
+      $ref: "./responses/406-VersionNotSupported.yml"
+    "501":
+      description: The server does not implement the info endpoint for evaluate.
+      $ref: "./responses/501-NotImplemented.yml"

paths/evaluate/schemas/EvaluateHealthResponse.yml

@@ -1,8 +1,7 @@
 type: object
-description: Health status and capabilities of the evaluate service.
+description: Health status of the evaluate service.
 required:
   - status
-  - capabilities
 properties:
   status:
     $ref: "../../shared/enums/HealthStatus.yml"
@@ -16,12 +15,3 @@ properties:
       - string
       - "null"
     description: Optional version of the evaluate service implementation.
-  requirements:
-    type:
-      - object
-      - "null"
-    description: Optional requirements clients must satisfy to use this service.
-    allOf:
-      - $ref: "./EvaluateRequirements.yml"
-  capabilities:
-    $ref: "./EvaluateCapabilities.yml"

paths/evaluate/schemas/EvaluateInfoResponse.yml

@@ -0,0 +1,19 @@
+type: object
+description: Information and capabilities of the evaluate service.
+required:
+  - capabilities
+properties:
+  version:
+    type:
+      - string
+      - "null"
+    description: Optional version of the evaluate service implementation.
+  requirements:
+    type:
+      - object
+      - "null"
+    description: Optional requirements clients must satisfy to use this service.
+    allOf:
+      - $ref: "./EvaluateRequirements.yml"
+  capabilities:
+    $ref: "./EvaluateCapabilities.yml"