Move version to header and flatten responses

Author: nbarbettini

spec/http/1.0/openapi.json

@@ -18,10 +18,20 @@
         "operationId": "health-check",
         "summary": "Check health",
         "description": "Checks the health status of the server.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/OXPVersionSelectorHeader"
+          }
+        ],
         "security": [{}],
         "responses": {
           "200": {
-            "description": "Server is healthy."
+            "description": "Server is healthy.",
+            "headers": {
+              "OXP-Version": {
+                "$ref": "#/components/headers/OXPServerHeader"
+              }
+            }
           },
           "503": {
             "description": "Server is unhealthy and cannot accept requests."
@@ -34,38 +44,29 @@
         "operationId": "list-tools",
         "summary": "List tools",
         "description": "Returns a list of tool definitions.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/OXPVersionSelectorHeader"
+          }
+        ],
         "security": [
           {
             "bearerAuth": []
           },
           {}
         ],
-        "requestBody": {
-          "required": false,
-          "content": {
-            "application/json": {
-              "schema": {
-                "properties": {
-                  "$schema": {
-                    "type": "string",
-                    "format": "uri"
-                  }
-                }
-              }
-            }
-          }
-        },
         "responses": {
           "200": {
             "description": "A list of available tools.",
+            "headers": {
+              "OXP-Version": {
+                "$ref": "#/components/headers/OXPServerHeader"
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
                   "properties": {
-                    "$schema": {
-                      "type": "string",
-                      "format": "uri"
-                    },
                     "items": {
                       "type": "array",
                       "items": {
@@ -79,7 +80,12 @@
             }
           },
           "401": {
-            "description": "Unauthorized. The request requires authentication, but the provided credentials are invalid or missing."
+            "description": "Unauthorized. The request requires authentication, but the provided credentials are invalid or missing.",
+            "headers": {
+              "OXP-Version": {
+                "$ref": "#/components/headers/OXPServerHeader"
+              }
+            }
           }
         }
       }
@@ -89,6 +95,11 @@
         "operationId": "call-tool",
         "summary": "Call tool",
         "description": "Calls a tool with the given parameters.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/OXPVersionSelectorHeader"
+          }
+        ],
         "security": [
           {
             "bearerAuth": []
@@ -100,42 +111,34 @@
           "content": {
             "application/json": {
               "schema": {
-                "properties": {
-                  "$schema": {
-                    "type": "string",
-                    "format": "uri"
-                  },
-                  "request": {
-                    "$ref": "#/components/schemas/CallToolRequest"
-                  }
-                },
-                "required": ["request"]
+                "$ref": "#/components/schemas/CallToolRequest"
               }
             }
           }
         },
         "responses": {
           "200": {
             "description": "Response from tool.",
+            "headers": {
+              "OXP-Version": {
+                "$ref": "#/components/headers/OXPServerHeader"
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
-                  "properties": {
-                    "$schema": {
-                      "type": "string",
-                      "format": "uri"
-                    },
-                    "result": {
-                      "$ref": "#/components/schemas/CallToolResponse"
-                    }
-                  },
-                  "required": ["result"]
+                  "$ref": "#/components/schemas/CallToolResponse"
                 }
               }
             }
           },
           "400": {
             "description": "The request is invalid or could not be processed.",
+            "headers": {
+              "OXP-Version": {
+                "$ref": "#/components/headers/OXPServerHeader"
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -144,11 +147,13 @@
               }
             }
           },
-          "401": {
-            "description": "Unauthorized. The request requires authentication, but the provided credentials are invalid or missing."
-          },
           "422": {
             "description": "The tool call is valid, but the parameters are invalid (missing, incorrect type, etc).",
+            "headers": {
+              "OXP-Version": {
+                "$ref": "#/components/headers/OXPServerHeader"
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -169,6 +174,25 @@
         "bearerFormat": "JWT"
       }
     },
+    "parameters": {
+      "OXPVersionSelectorHeader": {
+        "name": "OXP-Version",
+        "in": "header",
+        "description": "Optional header to specify the version of the OXP protocol to use.",
+        "required": false,
+        "schema": {
+          "type": "string"
+        }
+      }
+    },
+    "headers": {
+      "OXPServerHeader": {
+        "description": "The OXP version used by the server",
+        "schema": {
+          "type": "string"
+        }
+      }
+    },
     "schemas": {
       "ToolId": {
         "type": "string",