--- url: /services/managed/openapi.md description: >- Document Managed Service endpoints, inputs, and outputs using OpenAPI v3 so users understand how to call and consume your API. --- # Describe your API using OpenAPI Specification v3.0 A proper API description will help users of your service to understand how to use it. It is the technical interface of your API product and describes the input and output data that is required to execute the service. We use the [OpenAPI Specification v3 (OAS3)](https://swagger.io/specification) to describe the API of a service. ## Endpoints Managed Services expose an API to asynchronously execute the service and retrieve the results. The following table lists the available endpoints: | Method | Path | Description | |:-------|:----------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `GET` | `/` | Retrieves a list of all service executions. The response includes links to each service execution, allowing for further queries on their status and results. | | `POST` | `/` | This method is used to run the service asynchronously while sending the appropriate input. Accepts a JSON object, which will be passed to the service code (e.g., the `run()` method in the `program.py` file). The response contains the ID of the service execution. | | `GET` | `/{id}` | Check the status of a service execution. The status can be one of the following: `PENDING`, `RUNNING`, `SUCCEEDED`, `CANCELLED`, `FAILED`. The response also includes timestamps to provide information about when the execution was created, started, and completed. | | `GET` | `/{id}/result` | Get the result of a service execution. The response contains the JSON result from the service (if any). Further, it provides links to download all result files created during the service execution. | | `GET` | `/{id}/result/{file}` | Download a result file of a service execution. The content type of the HTTP response is set to the content type of the file. If it cannot be determined, the content type is set to `application/octet-stream`. | | `GET` | `/{id}/log` | Get the log output of a service execution line by line. | | `PUT` | `/{id}/cancel` | Cancels a `PENDING` or `RUNNING` service execution. | > \[!IMPORTANT] > Do **NOT** change the operations/endpoints or add new ones, otherwise communicating with the service will not work as intended. ## Describing your API > \[!NOTE] We provide a template!\ > Our default API description, which can be used as a template, can be downloaded: . As a service provider, you can (and should) change titles and descriptions for the different endpoints. Besides that, it is highly recommended to describe the format of the inputs and outputs withing the `components.schemas` section of the API specification. This is especially important for the `POST /` endpoint, since it defines what kind of input data may be provided by the user. Further, the response specification for `GET /{id}/result` endpoint is equally important, since it defines what kind of output the user can expect when successfully running the service. You may use the integrated Swagger Editor (Service Details > API Specification) to edit the API description. Alternatively, use the [Swagger Online Editor](https://editor.swagger.io) or an OpenAPI editor extensions for your IDE, e.g,. for [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi). ### Title and Description We highly recommend to change the title and description of the API to match your service. | Field | Description | |:-------------------|:--------------------------------| | `info.title` | The title of the API. | | `info.description` | A short description of the API. | Example: ```yaml info: title: Service API description: | API description for a managed Service. ``` ### Input Data and Parameters Each managed service retrieves input data and parameters from the user when executed via the `POST /` endpoint. | Field | Description | |:---------------------------------|:------------------------------------| | `components.schemas.InputData` | The schema of the input data. | | `components.schemas.InputParams` | The schema of the input parameters. | If you are using the [Starter template for Python projects](https://dashboard.hub.kipu-quantum.com/community/implementations/1a0ae675-4b23-405c-af8e-f4189ff14e0), the input data and parameters are defined by the signature of the `run()` method in the `program.py` file. For example, if you defined the `run()` method as `def run(data: Dict[str, Any], params: Dict[str, Any]) -> Dict[str, Any]:`, this could imply that users may send the following API request bodies: ```json { "data": { "values": [1, 2, 3] }, "params": { "round_up": true } } ``` In case you are using a [custom Docker Container](custom-containers), the platform ensures that the input provided via the Service API in the form of is mounted into the container at runtime. For example, given the input from above, the runtime creates the following files: * `data.json` with the content `{ "values": [1, 2, 3] }` * `params.json` with the content `{ "round_up": true }` These files are mounted into the directory `/var/runtime/input` of the running container. Either way, the input data and parameters should be described in the API description. For example, the following snippet describes the input data and parameters for a service that sums up a list of numbers and optionally rounds up the result. ```yaml components: schemas: InputData: type: object # # Define the schema of your input data here # properties: values: description: List of values to sum up type: array items: type: number example: [1, 2, 3] InputParams: type: object # # Define the schema of your input parameters here # properties: round_up: description: Whether to round up the result type: boolean example: true ``` In general, input data should encode the information about the actual problem (e.g., the entries of a QUBO-matrix) while input parameters are additional information to influence the evaluation (e.g., the number of ancillary qubits for an execution). Learn more about how to define the schema of your input data and parameters [here](https://swagger.io/specification/#schema-object) or which data types are supported [here](https://swagger.io/specification/#data-types). ### Responses (aka. Output) A service may produce different kinds of output. First, there is the return value of the `run()` method in the `program.py` file. The response type must be a JSON-serializable object, e.g., a dictionary or Pydantic model. This kind of output will be returned in the response of the `GET /{id}/result` endpoint. The respective schema should be defined in the `ResultResponse` section. | Field | Description | |:------------------------------------|:-----------------------------------| | `components.schemas.ResultResponse` | The schema of the result response. | Considering the example from above, the response of the `run()` method could be a dictionary with the sum of the values: `{ "sum": 6 }` This may result in the following schema definition: ```yaml components: schemas: ResultResponse: type: object additionalProperties: type: string properties: # # Add the schema of your result response here # sum: description: The sum of the values type: number example: 6 # DO NOT REMOVE THE FOLLOWING LINES _links: type: object properties: status: $ref: '#/components/schemas/HALLink' additionalProperties: $ref: '#/components/schemas/HALLink' _embedded: type: object properties: status: $ref: '#/components/schemas/ServiceExecution' ``` Learn more about how to define the schema of your input data and parameters [here](https://swagger.io/specification/#schema-object) or which data types are supported [here](https://swagger.io/specification/#data-types). Further, a service may write additional output data to files in the `/var/runtime/output` directory. These files can be downloaded by the user via the `GET /{id}/result/{file}` endpoint. The `ResultResponse` schema already defines a `_links` property that contains the respective download links. If the `run()` method returned a dictionary with the sum of the values, there will also be a file `output.json` containing the same information (`{ "sum": 6 }`). A full API response could look like this: ```json { "sum": 6, "_embedded": { "status": { "id": "ee49be82-593d-4d12-b732-ab84e0b11be1", "createdAt": "2025-03-14 14:09:33", "startedAt": "2025-03-14 14:10:45", "endedAt": "2025-03-14 14:11:00", "status": "SUCCEEDED" } }, "_links": { "self": { "href": "...service endpoint.../ee49be82-593d-4d12-b732-ab84e0b11be1/result" }, "status": { "href": "...service endpoint.../ee49be82-593d-4d12-b732-ab84e0b11be1" }, "hello.jpg": { "href": "...service endpoint.../ee49be82-593d-4d12-b732-ab84e0b11be1/result/hello.jpg" }, "output.json": { "href": "...service endpoint.../ee49be82-593d-4d12-b732-ab84e0b11be1/result/output.json" } } } ``` Last but not least, there is log output of a service. The complete log output can be retrieved line by line via the `GET /{id}/log` endpoint.