Ref: API Endpoints

Introduction

This document outlines some of the common built-in KOS API endpoints.

API

URL format

In KOS, endpoint URLs take the form:

http://{domain}:{port}/api/{app}/{path}

where:

http is the schema
{domain} is the domain name or IP address
{port} is the port number
api is the prefix used by all KOS endpoints, both built-in (provided by KOS) and custom (the ones you write)
{app} is the name of the application
- for built-in endpoints, this is "kos"
- for custom endpoints, this is the kos.app.appId value found in the app’s descriptor.json file, for example, "system"
{path} provides the controller base and all other path components and variable values

URL examples

In this article’s examples, we use:

{domain} = localhost
{port} = 8081
{app} = kos

like:

http://localhost:8081/api/kos/{path}

Substitute your domain and port values as necessary.

The HTTP method of each endpoint is GET unless specifically stated.

All Endpoints

View all endpoints

Returns all system endpoints, both built-in and custom:

http://localhost:8081/api/kos/openapi/api

View all built-in endpoints

Returns the list of all built-in endpoints:

http://localhost:8081/api/kos/openapi/api/kos

Sample output

{
  "openapi": "3.0.3",
  "info": {
    "title": "kos-api",
    "contact": {
      "name": "KOS Development Team",
      "url": "https://kosdev.com",
      "email": "info@kosdev.com"
    },
    "license": {
      "name": "KOS License",
      "url": "https://kosdev.com/license"
    },
    "version": "0.1.0"
  },
  "paths": {
    "/api/kos/ingredients": {
      "get": {
        "tags": [
          "Ingredient service"
        ],
        "summary": "Return the list of all currently known ingredients. (v1.0)",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "description": "(typeName=java.util.Collection<? extends com.tccc.kos.ext.dispense.service.ingredient.BaseIngredient>)",
                  "$ref": "#/components/schemas/bc759d95-061b-40ac-8a4a-6aaecaccf591"
                }
              }
            }
          }
        }
      }
    },
    "/api/kos/troubles": {
      "get": {
        "tags": [
          "Trouble service"
        ],
        "summary": "Return all available troubles. (v1.0)",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "description": "(viewName=Trouble$View)",
                  "$ref": "#/components/schemas/8440bc4d-64a5-44cc-865d-4cb2def1012b"
                }
              }
            }
          }
        }
      }
    },
    "/api/kos/config/schema": {
      "get": {
        "tags": [
          "Config service"
        ],
        "summary": "Return schema data about all known config data. This describes the structure of every known\nConfigBean. This is used by KOS Studio tools. (v1.0)",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "description": "(typeName=java.util.Collection<com.tccc.kos.commons.core.service.config.ConfigSchema>)",
                  "$ref": "#/components/schemas/58f34832-b534-441f-93cd-68b930e3212b"
                }
              }
            }
          }
        }
      }
    },
    "/api/kos/future/traces": {
      "get": {
        "tags": [
          "Future service"
        ],
        "summary": "Return the list of available future traces. Every future captures a trace of events that\nallow the future to be analyzed. A future can also declare itself a child of another future\nin which case the trace for the child future becomes a child of the parent trace which\nensures that parent traces can be analyzed with full context. The future service maintains\na limited queue of traces and this endpoint returns the contents of the queue. This\nonly includes the trace objects which describe structure and existence but no events.\nUse the events endpoint to fetch the event list for any future in the trace\n\nAs trace data is held in a queue, new traces will cause existing traces to be removed\nwhich means event data may not be available some time after this endpoint reports\nthe existence of the trace. (v1.0)",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "description": "(typeName=java.util.Collection<com.tccc.kos.commons.util.concurrent.future.trace.FutureTrace>)",
                  "$ref": "#/components/schemas/89ba4b8a-f477-4e54-8f70-2f36608c2a8d"
                }
              }
            }
          }
        }
      }
    },
    "/api/kos/handles": {
      "get": {
        "tags": [
          "Handle service"
        ],
        "summary": "Returns a list of all defined handle paths. Handles use weak references to their associated\nbeans which means that handles may exist for some time after the associated bean is\nno longer accessible or garbage collected. This endpoint exists primarily as a debugging\nresource and should not be used as the primary source of information about what objects\nactually exist in the system. (v1.0)",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "description": "(typeName=java.util.Collection<java.lang.String>)",
                  "$ref": "#/components/schemas/d90beb41-d117-4c3c-8d20-012e0c46318a"
                }
              }
            }
          }
        }
      }
    },
    "/api/kos/holders": {
      "get": {
        "tags": [
          "Holder service"
        ],
        "summary": "Return the list of all currently defined holders. (v1.0)",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "description": "(viewName=Holder$View)",
                  "$ref": "#/components/schemas/57e3d265-5de9-45a0-9fb4-814ee0993ccf"
                }
              }
            }
          }
        }
      }
    },
    "/api/kos/chrome": {
      "get": {
        "tags": [
          "Chrome service"
        ],
        "summary": "Return available chrome browser instances. (v1.0)",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "description": "(viewName=ChromeBrowser$Summary)",
                  "$ref": "#/components/schemas/c17a1e11-4684-4445-a121-6814b587c462"
                }
              }
            }
          }
        }
      }
    },
    "/api/kos/descriptor/{path}": {
      "get": {
        "tags": [
          "Descriptor service"
        ],
        "summary": "Returns the entire descriptor for the HandleAware object with the specified path. (v1.0)",
        "parameters": [
          {
            "name": "path",
            "in": "path",
            "description": "Handle path of the object to return the descriptor for.",
            "required": true,
            "schema": {
              "type": "string",
              "description": "(handleVar=com.tccc.kos.commons.util.json.JsonDescriptorAware)"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "(viewName=HandleView)"
                }
              }
            }
          }
        }
      }
    },
    "/api/kos/assignments": {
      "get": {
        "tags": [
          "Ingredient assignment service"
        ],
        "summary": "Returns all existing ingredient assigments. (v1.0)",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "description": "(typeName=java.util.Collection<com.tccc.kos.ext.dispense.service.assignment.Assignment>)",
                  "$ref": "#/components/schemas/6b8e14c8-6121-461e-a412-504b628fe645"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Ingredient assignment service"
        ],
        "summary": "Create a new ingredient assignment for the specified holder. If an existing\nassignment exists for the holder, it will be removed as part of adding the\nnew mapping. (v1.0)",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "description": "(typeName=com.tccc.kos.ext.dispense.service.assignment.Assignment)",
                "$ref": "#/components/schemas/64488306-55a7-40a2-bc9e-56963bd56672"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "description": "(typeName=com.tccc.kos.ext.dispense.service.assignment.Assignment)",
                  "$ref": "#/components/schemas/64488306-55a7-40a2-bc9e-56963bd56672"
                }
              }
            }
          }
        }
      }
    },
    "/api/kos/regions/info": {
      "get": {
        "tags": [
          "Region service"
        ],
        "summary": "Return available unit systems and time / date formats. (v1.0)",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "description": "(typeName=com.tccc.kos.core.service.region.RegionInfo)",
                  "$ref": "#/components/schemas/fdff2c17-4e3c-426a-8b35-428220df36c4"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
    }
  },
  "tags": [
    {
      "name": "Ingredient service",
      "description": "Access to currently installed ingredients."
    },
    {
      "name": "Trouble service",
      "description": "List and resolve troubles."
    },
    {
      "name": "Config service",
      "description": "Ability to configure beans within KOS."
    },
    {
      "name": "Future service",
      "description": "Cancel futures and access to future trace data."
    },
    {
      "name": "Handle service",
      "description": "Access to all HandleAware objects in KOS."
    },
    {
      "name": "Holder service",
      "description": "Access to all holders in the device."
    },
    {
      "name": "Chrome service",
      "description": "Access to chrome operations."
    },
    {
      "name": "OpenAPI service",
      "description": "Dynamically create OpenAPI docs for endpoints."
    },
    {
      "name": "Descriptor service",
      "description": "Access to JsonDescriptor from HandleAware objects in KOS."
    },
    {
      "name": "Ingredient assignment service",
      "description": "Support for persistent ingredient assignments to holders."
    },
    {
      "name": "Region service",
      "description": "Access to available regions."
    }
  ]
}

View all custom endpoints

Returns the list of all custom endpoints for the "system" app:

http://localhost:8081/api/kos/openapi/api/system

Descriptor

View core assembly descriptor

Returns the core assembly’s JSON descriptor file:

http://localhost:8081/api/kos/assembly.core

Returns a subset of the core assembly’s JSON descriptor file:

http://localhost:8081/api/kos/assembly.core/some.dotted.path

Handles

Handles are simply the names of software objects.

View all handles

http://localhost:8081/api/kos/handles

Sample output

{
  "status": 200,
  "version": {
    "major": 1,
    "minor": 0
  },
  "data": [
    "assembly.core",
    "assembly.core.board:leftBoard",
    "assembly.core.board:leftBoard.pump:A1",
    "assembly.core.board:leftBoard.pump:A2",
    "assembly.core.board:leftBoard.pump:A3",
    "assembly.core.board:leftBoard.pump:CW1",
    "assembly.core.board:leftBoard.pump:F1",
    "assembly.core.board:leftBoard.pump:F2",
    "assembly.core.board:leftBoard.pump:F3",
    "assembly.core.board:leftBoard.pump:F4",
    "assembly.core.board:leftBoard.pump:PW1",
    "assembly.core.board:leftBoard.pump:S1",
    "assembly.core.board:leftBoard.pump:S2",
    "assembly.core.board:leftBoard.pump:S3",
    "assembly.core.board:leftBoard.pump:S4",
    "assembly.core.board:leftBoard.pump:S5",
    "assembly.core.board:leftBoard.pump:S6",
    "assembly.core.board:leftBoard.pump:S7",
    "assembly.core.board:rightBoard",
    "assembly.core.board:rightBoard.pump:A4",
    "assembly.core.board:rightBoard.pump:A5",
    "assembly.core.board:rightBoard.pump:A6",
    "assembly.core.board:rightBoard.pump:CW3",
    "assembly.core.board:rightBoard.pump:F5",
    "assembly.core.board:rightBoard.pump:F6",
    "assembly.core.board:rightBoard.pump:F7",
    "assembly.core.board:rightBoard.pump:F8",
    "assembly.core.board:rightBoard.pump:PW3",
    "assembly.core.board:rightBoard.pump:S10",
    "assembly.core.board:rightBoard.pump:S11",
    "assembly.core.board:rightBoard.pump:S12",
    "assembly.core.board:rightBoard.pump:S13",
    "assembly.core.board:rightBoard.pump:S14",
    "assembly.core.board:rightBoard.pump:S8",
    "assembly.core.board:rightBoard.pump:S9",
    "assembly.core.holder:A1",
    "assembly.core.holder:A2",
    "assembly.core.holder:A3",
    "assembly.core.holder:A4",
    "assembly.core.holder:A5",
    "assembly.core.holder:A6",
    "assembly.core.holder:CW1",
    "assembly.core.holder:CW3",
    "assembly.core.holder:F1",
    "assembly.core.holder:F2",
    "assembly.core.holder:F3",
    "assembly.core.holder:F4",
    "assembly.core.holder:F5",
    "assembly.core.holder:F6",
    "assembly.core.holder:F7",
    "assembly.core.holder:F8",
    "assembly.core.holder:PW1",
    "assembly.core.holder:PW3",
    "assembly.core.holder:S1",
    "assembly.core.holder:S10",
    "assembly.core.holder:S11",
    "assembly.core.holder:S12",
    "assembly.core.holder:S13",
    "assembly.core.holder:S14",
    "assembly.core.holder:S2",
    "assembly.core.holder:S3",
    "assembly.core.holder:S4",
    "assembly.core.holder:S5",
    "assembly.core.holder:S6",
    "assembly.core.holder:S7",
    "assembly.core.holder:S8",
    "assembly.core.holder:S9",
    "assembly.core.nozzle:leftNozzle",
    "assembly.core.nozzle:leftNozzle.pipeline:pour",
    "assembly.core.nozzle:leftNozzle.pipeline:pour.engine",
    "assembly.core.nozzle:leftNozzle.pipeline:pump",
    "assembly.core.nozzle:rightNozzle",
    "assembly.core.nozzle:rightNozzle.pipeline:pour",
    "assembly.core.nozzle:rightNozzle.pipeline:pour.engine",
    "assembly.core.nozzle:rightNozzle.pipeline:pump",
    "kos.service:apiClient",
    "kos.service:app",
    "kos.service:assembly",
    "kos.service:assignment",
    "kos.service:blink",
    "kos.service:brokerRouterBridge",
    "kos.service:chrome",
    "kos.service:config",
    "kos.service:extension",
    "kos.service:finder",
    "kos.service:fuse",
    "kos.service:fuseLogger",
    "kos.service:future",
    "kos.service:handle",
    "kos.service:hardware",
    "kos.service:holder",
    "kos.service:ingredient",
    "kos.service:insertion",
    "kos.service:insertion.filter:ingredientFilter",
    "kos.service:kab",
    "kos.service:manifest",
    "kos.service:messageBroker",
    "kos.service:nodeMgr",
    "kos.service:nozzle",
    "kos.service:region",
    "kos.service:region.source",
    "kos.service:spawn",
    "kos.service:trouble",
    "system.app"
  ]
}

Configuration

View all configs

http://localhost:8081/api/kos/config/schema

Ingredients

View all ingredients

http://localhost:8081/api/kos/ingredients

Holders

View all holders

http://localhost:8081/api/kos/holders

Regions

View all regions

http://localhost:8081/api/kos/regions/info

Assignments

View all assignments

http://localhost:8081/api/kos/assignments

Chrome

View all instances

http://localhost:8081/api/kos/chrome

Futures

View all futures

http://localhost:8081/api/kos/future/traces

Troubles

View all troubles

http://localhost:8081/api/kos/troubles