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) 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	/	Health checking endpoint. Gives the user the information, whether the service is available at all.
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

We provide a template!

Our default API description, which can be used as a template, is available to download.

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 or an OpenAPI editor extensions for your IDE, e.g,. for Visual Studio Code.

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:

info:
  title: PLANQK Service API
  description: |
    API description for a managed PLANQK 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 PLANQK starter template for Python projects, 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:

{ 
  "data": { "values": [1, 2, 3] }, 
  "params": { "round_up": true } 
}

In case you are using a custom Docker Container, PLANQK 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.

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 or which data types are supported here.

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:

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 or which data types are supported here.

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:

{
  "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.