From 58c32dfdcb64ae6b15ca0f5e2e7d585e396658cc Mon Sep 17 00:00:00 2001 From: Marcus Messer Date: Mon, 25 May 2026 16:19:37 +0100 Subject: [PATCH 1/4] Split health and capabilities endpoints for chat service --- openapi.yml | 2 + paths/chat/chat-health.yml | 22 ++-------- paths/chat/chat-info.yml | 52 +++++++++++++++++++++++ paths/chat/schemas/ChatHealthResponse.yml | 5 +-- paths/chat/schemas/ChatInfoResponse.yml | 12 ++++++ 5 files changed, 71 insertions(+), 22 deletions(-) create mode 100644 paths/chat/chat-info.yml create mode 100644 paths/chat/schemas/ChatInfoResponse.yml diff --git a/openapi.yml b/openapi.yml index 909544c..6e44a55 100644 --- a/openapi.yml +++ b/openapi.yml @@ -26,5 +26,7 @@ paths: $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" diff --git a/paths/chat/chat-health.yml b/paths/chat/chat-health.yml index 4d3ec90..e8ae42b 100644 --- a/paths/chat/chat-health.yml +++ b/paths/chat/chat-health.yml @@ -1,10 +1,9 @@ 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: @@ -12,7 +11,7 @@ get: - $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": diff --git a/paths/chat/chat-info.yml b/paths/chat/chat-info.yml new file mode 100644 index 0000000..6443884 --- /dev/null +++ b/paths/chat/chat-info.yml @@ -0,0 +1,52 @@ +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: + status: "OK" + 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 health endpoint for chat. + $ref: "./responses/501-NotImplemented.yml" diff --git a/paths/chat/schemas/ChatHealthResponse.yml b/paths/chat/schemas/ChatHealthResponse.yml index 0f3fa98..5911f7b 100644 --- a/paths/chat/schemas/ChatHealthResponse.yml +++ b/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" diff --git a/paths/chat/schemas/ChatInfoResponse.yml b/paths/chat/schemas/ChatInfoResponse.yml new file mode 100644 index 0000000..6abed99 --- /dev/null +++ b/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" From 16e89d167c13e541a4662ca9663fafbcf4cc039c Mon Sep 17 00:00:00 2001 From: Marcus Messer Date: Mon, 25 May 2026 16:21:54 +0100 Subject: [PATCH 2/4] Fix typo in description for chat info endpoint --- paths/chat/chat-info.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/paths/chat/chat-info.yml b/paths/chat/chat-info.yml index 6443884..736cfa1 100644 --- a/paths/chat/chat-info.yml +++ b/paths/chat/chat-info.yml @@ -48,5 +48,5 @@ get: "406": $ref: "./responses/406-VersionNotSupported.yml" "501": - description: The server does not implement the health endpoint for chat. + description: The server does not implement the info endpoint for chat. $ref: "./responses/501-NotImplemented.yml" From 5c545e082e27023b23090a0e13c92126a9980b1a Mon Sep 17 00:00:00 2001 From: Marcus Messer Date: Mon, 25 May 2026 16:24:26 +0100 Subject: [PATCH 3/4] Split health and capabilities endpoints for evaluate service --- openapi.yml | 2 + paths/evaluate/evaluate-health.yml | 25 +------- paths/evaluate/evaluate-info.yml | 57 +++++++++++++++++++ .../schemas/EvaluateHealthResponse.yml | 12 +--- .../evaluate/schemas/EvaluateInfoResponse.yml | 19 +++++++ 5 files changed, 81 insertions(+), 34 deletions(-) create mode 100644 paths/evaluate/evaluate-info.yml create mode 100644 paths/evaluate/schemas/EvaluateInfoResponse.yml diff --git a/openapi.yml b/openapi.yml index 6e44a55..2002610 100644 --- a/openapi.yml +++ b/openapi.yml @@ -22,6 +22,8 @@ tags: paths: /evaluate: $ref: "./paths/evaluate/evaluate.yml" + /evaluate/info: + $ref: "./paths/evaluate/evaluate-info.yml" /evaluate/health: $ref: "./paths/evaluate/evaluate-health.yml" /chat: diff --git a/paths/evaluate/evaluate-health.yml b/paths/evaluate/evaluate-health.yml index 36cacdc..84097d1 100644 --- a/paths/evaluate/evaluate-health.yml +++ b/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,24 +31,6 @@ get: status: "OK" message: "Service healthy" 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": diff --git a/paths/evaluate/evaluate-info.yml b/paths/evaluate/evaluate-info.yml new file mode 100644 index 0000000..84d067d --- /dev/null +++ b/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" diff --git a/paths/evaluate/schemas/EvaluateHealthResponse.yml b/paths/evaluate/schemas/EvaluateHealthResponse.yml index ae612f0..c0b3b53 100644 --- a/paths/evaluate/schemas/EvaluateHealthResponse.yml +++ b/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" diff --git a/paths/evaluate/schemas/EvaluateInfoResponse.yml b/paths/evaluate/schemas/EvaluateInfoResponse.yml new file mode 100644 index 0000000..8da29ca --- /dev/null +++ b/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" From 92593c8893598a417e14161c204a9e17ecf9b9fd Mon Sep 17 00:00:00 2001 From: Marcus Messer Date: Mon, 25 May 2026 17:43:06 +0100 Subject: [PATCH 4/4] Remove unused `status` field from chat-info example --- paths/chat/chat-info.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/paths/chat/chat-info.yml b/paths/chat/chat-info.yml index 736cfa1..5a236db 100644 --- a/paths/chat/chat-info.yml +++ b/paths/chat/chat-info.yml @@ -30,7 +30,6 @@ get: exampleInfo: summary: Example service with capabilities value: - status: "OK" version: "1.0.0" capabilities: supportsChat: true