KOS Developer's Portal

API Endpoints

Introduction

Before we go any further, let’s take a look at the REST API endpoints that are available in our KOS application. We can not only view the methods and parameters, but can also import the entire graph into tools such as Postman.

A Look Back

Back in the REST Controller tutorial, we looked at how to create and hit an HTTP endpoint. For example, the following GET request:

http://localhost:8081/api/system/mycontroller/ping

resulted in the following response:

{
  "status": 200,
  "version": {
    "major": 1,
    "minor": 0
  },
  "data": "pong"
}

This gives us the ability to verify that our KOS application is running.

Viewing Endpoints

In addition to creating our own API, KOS provides many HTTP endpoints right out of the box. But what are they?

KOS gives you an easy way to see every endpoint. This includes every KOS built-in endpoint and every custom HTTP method you write.

We’ll explore what these are and how to take advantage of them in future articles, but for now we just want to understand that these are available and to get a taste.

All endpoints

To see all API endpoints, fetch the following URL in your browser:

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

You’ll get a long listing like this:

{
  "openapi": "3.0.3",
  "info": {
    "title": "kos_restful_api_endpoints",
    "contact": {
      "name": "KOS Development Team",
      "url": "https://dev-portal-domain",
      "email": "info@kos-team.com"
    },
    "license": {
      "name": "KOS License",
      "url": "https://dev-portal-domain/license-page"
    },
    "version": "0.0.4"
  },
  "paths": { (1)
    "/api/kos/holders": { (2)
      "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/367b7f12-9def-4900-a900-e600c2d082ef"
                }
              }
            }
          }
        }
      }
    },
    "/api/kos/ingredients": { (3)
      "get": {
        "tags": [

. . . . (the rest is truncated) . . . .

1	List of all URL paths
2	Returns list of all holders
3	Returns list of all ingredients

This is the description of all endpoints, using the OpenAPI specification.

If you scroll down a ways, or search for "mycontroller", you’ll see a recognizable path:

    "/api/system/mycontroller/ping": { (1)
      "get": {
        "tags": [
          "My first KOS REST controller"
        ],
        "summary": "checks to see if controller is running (v1.0)", (2)
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string" (3)
                }
              }
            }
          }
        }
      }
    },

    . . . .

1	This is our custom "ping" endpoint
2	The method’s description and version number
3	It returns a string

To download the full JSON data, select "File > Save Page As" (or equivalent) and save the file to something called my-kos-app.json. This file is used in some of the following sections.

Tip

It bears repeating that you can view all built-in and custom HTTP endpoints in OpenAPI format using the URL:

http://{domain}:{port}/api/kos/openapi/api

Subset of endpoints

This graph can get quite large, so KOS provides a way to filter the output.

To see only your custom application endpoints, add /system to the URL (because your appId is "system") :

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

To see only your custom "mycontroller" endpoints, append /mycontroller to that URL:

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

To see only a "user" method in your custom controller, append /user to that URL:

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

Now that we see the pattern, {baseUrl} describes the URL path to match (filter) on:

http://localhost:8081/api/kos/openapi/api/{baseUrl}

API Tools

The section describes how to import and use the KOS API specification in a couple popular third-party tools.

Postman

The section describes how to use the KOS API specification in Postman.

1) Open Postman, click on the APIs left-side menu, open the New API dropdown, then click Import:

Figure 1. Preparing to import into Postman

2) Navigate to and select the my-kos-app.json file downloaded above.

3) Postman imports the data and displays a screen like this:

Figure 2. The KOS API, after importing the OpenAPI JSON document into Postman

SwaggerHub

Another alternative that allows you to view the API is SwaggerHub.

1) Create an account and login at SwaggerHub.

2) On the top-left menu, select Create New > Import and Document API.

3) Select the my-kos-app.json file downloaded earlier and click the Upload File button.

4) Click the Import Definition button.

5) The imported API is now displayed:

Figure 3. After importing KOS API into SwaggerHub

Other

There are other ways to view and/or execute the KOS API. For simple GETs, you can use a browser’s URL line. There also a number of alternatives to Postman and Swagger. All our tutorial examples use Postman.

Test It Out

Let’s try a few endpoints. Your KOS application should be running.

View handles

Handles are names of objects in your software. To see a list of all object handles, use this endpoint:

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

Using Postman, we see the results. Notice all the KOS services.

Figure 4. All handles

View object using its handle

When we have an object’s handle, we can view it using:

http://localhost:8081/api/kos/handles/kos.service:app

postman view kos service app using handle

Figure 5. Viewing a service using its handle

View configuration

This endpoint shows the configuration for all objects in the system.

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

Figure 6. Config details

Summary

In this article, we learned how to:

Retrieve the HTTP API exposed by KOS, both built-in and custom endpoints
Import the OpenAPI JSON file into third-party tools such as Postman
Hit endpoints using Postman, allowing us to experiment with the API

We’ll visit more endpoints and explore all the data they provide in future tutorials.

Next up, we’ll build a demo dispenser.