API Browser

The API Browser is a comprehensive tool in KOS Studio that enables developers to explore and understand the APIs available on their connected device or simulator. When developing applications for KOS devices, knowing what APIs are available, understanding their endpoints, parameters, and expected responses is essential for efficient development. The API Browser provides a centralized location to discover APIs, view detailed endpoint documentation, and quickly extract the information you need to integrate these APIs into your code.

Whether you’re a hardware developer looking for device control APIs or a UI developer seeking APIs for user interactions, the API Browser helps you find what you need through powerful search and filtering capabilities. The tool also enables you to export API specifications to external tools like Postman or copy code snippets directly into your development environment.

Understanding KOS APIs

KOS devices expose their functionality through well-defined APIs that applications can call to interact with hardware, access data, and perform operations. These APIs follow standard REST principles and are organized by the applications that provide them.

API Organization
APIs are grouped by the KOS applications running on the device. Each application may provide one or more APIs, and each API contains multiple endpoints for specific operations.

Endpoint Structure
Each endpoint represents a specific operation you can perform, such as retrieving configuration, controlling hardware, or initiating an action. Endpoints include:

  • A path that identifies the operation
  • Parameters that customize the behavior
  • Request and response structures that define the data format
  • Descriptions that explain the purpose and usage

Why API Browser Matters
Without the API Browser, developers would need to manually search through documentation, examine code, or experiment with trial and error to discover available APIs. The API Browser makes this process instant and provides all the information you need in one place, directly connected to your running device.

Accessing the API Browser

Opening the Tool

  1. Log into KOS Studio
  2. In the Connection Manager window, locate your running image (connected to a simulator or device)
  3. Find the Active Tools section for that connection
  4. Click + Start New Tool
  5. Select API Browser from the dropdown menu

Note: The API Browser is available for both virtual devices (simulators) and connected physical devices.

Understanding the API Browser Interface

The API Browser uses two windows to organize information:

API Browser Main Window

The main window titled “API Browser” displays a list of all APIs available on the connected device. This provides your starting point for exploring what the device can do.

API Details Window

When you select an API, a second window titled “Endpoint Details for [API Name]” opens, showing comprehensive information about that specific API’s endpoints.

Browsing Available APIs

Viewing the API List

When you open the API Browser, you’ll see a comprehensive list of all APIs available on your connected device. The list is organized alphabetically by application, making it easy to scan and find what you’re looking for.

Information Displayed:

  • API Name: The identifier for the API
  • Description: A summary of what the API does and its primary purpose

Searching for APIs

To quickly find APIs related to specific functionality:

  1. Use the Search box at the top of the Available APIs window
  2. Type a search term related to the functionality you need
  3. The list updates to show only APIs that match your search

Search Behavior:

Comprehensive Matching:
The search looks for your term in multiple places and highlights the term in search results if term found in:

  • API names
  • API descriptions
  • Endpoint paths within APIs
  • Endpoint descriptions

Match Indicators:
For each API in the search results, you’ll see:

  • The API name and description
  • Endpoints that also include the search term
  • The endpoint path (if it contains the search term)
  • The endpoint description (if it contains the search term)
  • The number of times your search term appears within that API’s endpoints

Multiple Search Terms:
You can add additional search terms to narrow your results:

  • Enter an additional term to see only APIs matching all terms
  • Remove terms to broaden your search again
  • The list updates dynamically as you modify your search

No Results:
If no APIs match your search term, you’ll see a “no search found” message indicating that the term doesn’t appear in any available APIs.

Example Use Case:
A hardware developer searching for “pump” might find device control APIs, while a UI developer searching for “pour” might find the same APIs from a different perspective. The search accommodates different terminology for the same functionality.

Filtering APIs by Application

To focus on APIs from specific applications:

  1. Click the Filter button at the top of the Available APIs window
  2. A dropdown appears showing all applications that provide APIs on the device
  3. Select or unselect applications to control which APIs are displayed
  4. The list updates to show only APIs from selected applications

Managing Filters:

  • You can select multiple applications simultaneously
  • A list of active filters appears, allowing you to see what’s currently filtered
  • Click to remove individual filters
  • Clear all filters to see the complete API list again

Filtering is particularly useful when you know which application provides the functionality you need or when you want to explore what a specific application offers.

Exporting to Postman

To use the APIs in Postman for testing or development:

  1. Click the Export to Postman button in the Available APIs window
  2. The complete OpenAPI specification for the connected device is copied to your clipboard in JSON format
  3. Open Postman and import the specification
  4. You can now test and interact with the device’s APIs directly from Postman

This feature is valuable when you need to experiment with API calls, test payloads, or document API behavior outside of KOS Studio.

Viewing API Details

Opening the Details Window

To see comprehensive information about a specific API:

  1. Select an API from the Available APIs list
  2. The API Details window opens automatically with window title showing “Endpoint Details for [API Name]”

Details Window Structure

The API Details window is divided into two sections:

Left Panel – Endpoint List:

  • Shows all endpoints available in the selected API
  • Each endpoint displays its path and description
  • Endpoints are selectable to view their complete details

Right Panel – Endpoint Details:

  • Displays comprehensive information about the selected endpoint
  • Shows expandable sections with parameters, requests, and responses
  • Provides all the information you need to use the endpoint

Understanding Endpoint Information

When you select an endpoint from the list, the details panel shows:

HTTP Method:

The HTTP method indicating if request is GET, POST, PUT, and DELETE action.

Endpoint Path:
The URL path used to call this endpoint, such as /api/device/status or /api/control/pump/start

Description:
A detailed explanation of what the endpoint does, when to use it, and any important considerations

Path Parameters:
Parameters that appear in the URL path, with details including:

  • Name: The parameter identifier
  • Type: The data type (string, integer, etc.)
  • Description: What the parameter controls or represents

Request Information:
Details about the data you send when calling this endpoint:

  • JavaDocs Link: Reference documentation for related classes
  • Name: The request object or parameter name
  • Type: The data structure type

Response Information:
Details about the data the endpoint returns:

  • JavaDocs Link: Reference documentation for related classes
  • Name: The response object name
  • Type: The data structure type

Expandable Sections:
Click to expand sections to see full details about parameters, request bodies, and response structures.

Searching Within an API

When an API has many endpoints, use the search feature in the API Details window:

  1. Use the Search box in the API Details window
  2. Type a term related to the specific functionality you’re looking for
  3. The endpoint list updates to show only matching endpoints

Search Highlighting:

  • Your search term is highlighted wherever it appears
  • Highlights appear in endpoint paths, descriptions, and details
  • You can see at a glance where and how many times the term appears

Match Count:
The search results show how many times your search keyword appears within each matching endpoint, helping you identify the most relevant endpoints.

Exporting API Details

From the API Details window, you have several export options:

Copy to Clipboard

  1. Click the Copy to Clipboard button
  2. The OpenAPI specification for this specific API is copied to your clipboard in JSON format
  3. Import into Postman to work with this API’s endpoints

Copy with Parameters:

  1. Select an endpoint
  2. Click Copy with Parameters
  3. The endpoint path with parameter placeholders is copied to your clipboard
  4. Paste into your code and replace placeholders with actual values
  5. Example: /api/control/pump/{pumpId}/start where {pumpId} is a placeholder

Copy with TypeScript:

  1. Select an endpoint
  2. Click Copy with TypeScript
  3. A TypeScript code snippet for calling the endpoint is copied to your clipboard
  4. Paste directly into your TypeScript code
  5. The snippet includes proper typing and structure for the endpoint call

These export options significantly speed up development by providing ready-to-use code and documentation.

Practical Usage Scenarios

Discovering Available Functionality

When starting development on a new device:

  1. Open API Browser to see all available APIs
  2. Review API names and descriptions to understand capabilities
  3. Use search to find APIs related to your specific needs
  4. Open API Details for promising APIs to understand endpoints
  5. Export to Postman to experiment with calls before coding

Finding Specific Operations

When you need to perform a specific operation:

  1. Use the search feature with operation-related terms
  2. Review matching APIs and endpoints
  3. Read endpoint descriptions to verify functionality
  4. Check parameters and responses to understand requirements
  5. Copy code snippets to integrate into your application

Understanding Application Capabilities

To learn what a specific application provides:

  1. Use the filter to show only APIs from that application
  2. Browse the filtered list to see all exposed functionality
  3. Open details for interesting APIs
  4. Document the capabilities for your team or project

Integrating APIs into Code

When ready to implement API calls:

  1. Find the endpoint you need using search or browsing
  2. Open the API Details window
  3. Review parameters and response structures
  4. Use “Copy with TypeScript” to get starter code
  5. Or use “Copy with Parameters” to get the path with placeholders
  6. Paste into your code and customize as needed

Sharing API Documentation

When collaborating with team members:

  1. Open the API you want to document
  2. Use “Download to PDF” to create comprehensive documentation
  3. Share the PDF with colleagues who may not have device access
  4. Or use “Export to Postman” and share the JSON specification
  5. Team members can import into their own Postman environments

Testing API Behavior

Before implementing API calls in your application:

  1. Export the API specification to Postman
  2. Use Postman to send test requests with various parameters
  3. Observe responses and behavior
  4. Verify error handling and edge cases
  5. Once confident, implement in your KOS application

Tips for Effective Use

  • Start with search: Use descriptive terms related to what you want to accomplish rather than browsing the full list
  • Read descriptions carefully: Endpoint descriptions often contain important usage notes and considerations
  • Check parameter types: Understanding parameter types prevents runtime errors and helps with validation
  • Copy snippets liberally: Use the TypeScript copy feature to maintain consistency and reduce typing errors
  • Use search highlighting: The highlighted search terms help you quickly identify the most relevant information