openapi.yaml

openapi: 3.0.0
info:
  title: Infernet Router API
  version: 1.0.0
  description: API to interact with the Infernet network via the router
  contact:
    name: Stelios Rousoglou
    email: stelios@ritual.net
  license:
    name: BSD-3-Clause
    url: https://opensource.org/licenses/BSD-3-Clause
servers:
  - url: '{baseUrl}'
    variables:
      baseUrl:
        default: http://localhost:5000/api/v1
        description: Development server
  - url: 'https://infernet-router.ritual.net/api/v1'
    description: Production server

paths:
  /ips:
    get:
      summary: Returns IPs of nodes that can fulfill a job request
      operationId: getIps
      tags:
        - Network
      parameters:
        - in: query
          name: container
          required: true
          description: Container identifiers to filter the nodes by
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - in: query
          name: n
          required: false
          description: Number of IPs to return
          schema:
            type: integer
            default: 3
        - in: query
          name: offset
          required: false
          description: Offset in the list of IPs
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                description: List of IPs
                items:
                  type: string
        '400':
          description: Bad request due to missing parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /containers:
    get:
      summary: Returns containers running across the network
      operationId: getContainers
      tags:
        - Network
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Container'

  /resources:
    get:
      summary: Retrieves container resources for nodes in the network
      description: Collects hardware resources and available models for each container / service, on each node in the network
      parameters:
        - name: model_id
          in: query
          description: Model ID to check containers for.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: If model_id is provided, returns support information for containers on each node. Otherwise, returns all resources for containers on each node.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/NodeToContainerToModelSupportMap'
                  - $ref: '#/components/schemas/NodeToContainerToResourcesMap'

components:
  schemas:
    Container:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the container
        count:
          type: integer
          description: Number of instances of the container
        description:
          type: string
          description: Description of the container
      required:
        - id
        - count
    Error:
      type: object
      properties:
        error:
          type: string

    ContainerToModelSupportMap:
      type: object
      description: A mapping from container IDs to objects indicating model support.
      additionalProperties:
        type: object
        properties:
          supported:
            type: boolean
            description: Indicates if the model is supported by the container.
          error:
            type: string
            description: Describes the error in checking the model support.
        required:
          - supported

    NodeToContainerToModelSupportMap:
      type: object
      description: A mapping from node hostnames / IP addresses to ContainerToModelSupportMap objects.
      additionalProperties:
        $ref: '#/components/schemas/ContainerToModelSupportMap'

    MLModel:
      type: object
      required:
        - owner
      properties:
        owner:
          type: string
          description: The organization that owns the model.
        name:
          type: string
          description: The name of the model.
        repository:
          type: string
          description: The repository where the model is stored.
        storage:
          type: string
          description: The storage backend where the model is stored
        files:
          type: array
          items:
            type: string
          description: List of files associated with the model.
        version:
          type: string
          description: The version of the model.
        ml_type:
          type: string
          description: The type of machine learning model.

    ComputeCapability:
      type: object
      required:
        - id
        - type
        - task
      properties:
        id:
          type: string
          description: Identifier for the compute capability.
        type:
          type: string
          description: Type of inference service (e.g., CSS, ONNX).
        task:
          type: array
          items:
            type: string
          description: List of tasks supported by the compute capability.
        models:
          type: array
          items:
            $ref: '#/components/schemas/MLModel'
          description: List of models available for computation.
        cached_models:
          type: array
          items:
            $ref: '#/components/schemas/MLModel'
          description: List of models that are cached for faster access.
        inference_engine:
          type: string
          description: Inference engine used by the compute capability.
        inference_engine_version:
          type: string
          description: Version of the inference engine.

    HardwareCapability:
      type: object
      properties:
        capability_id:
          type: string
          description: Unique identifier for the hardware capability.
        cpu_info:
          $ref: '#/components/schemas/CPUInfo'
        disk_info:
          type: array
          items:
            $ref: '#/components/schemas/DiskInfo'
        os_info:
          $ref: '#/components/schemas/OSInfo'

    CPUInfo:
      type: object
      properties:
        architecture:
          type: string
        byte_order:
          type: string
        cores:
          type: array
          items:
            type: string
        model:
          type: string
        num_cores:
          type: integer
        vendor_id:
          type: string

    DiskInfo:
      type: object
      properties:
        available:
          type: integer
        filesystem:
          type: string
        mount_point:
          type: string
        size:
          type: integer
        used:
          type: integer

    OSInfo:
      type: object
      properties:
        name:
          type: string
        version:
          type: string
      required:
        - name
        - version

    ContainerToResourcesMap:
      type: object
      description: A mapping from container IDs to available resources.
      additionalProperties:
        type: object
        properties:
          service_id:
            type: string
            description: The unique identifier for the inference service.
          compute_capability:
            type: array
            description: List of compute capabilities available for the service.
            items:
              $ref: '#/components/schemas/ComputeCapability'
          hardware_capabilities:
            type: array
            description: List of hardware capabilities available for the service.
            items:
              $ref: '#/components/schemas/HardwareCapability'
        required:
          - service_id
          - compute_capability
          - hardware_capabilities

    NodeToContainerToResourcesMap:
      type: object
      description: A mapping from node hostnames / IP addresses to ContainerToResourcesMap objects.
      additionalProperties:
        $ref: '#/components/schemas/ContainerToResourcesMap'