Swagger UI Guide

This guide explains how to use the interactive Swagger UI to explore, test, and understand the Elements Hub REST API without writing any code.

Accessing Swagger UI

1. Start Elements Hub Server

Ensure your Elements Hub server is running. By default, it runs on http://localhost:42042

Replace localhost:42042 with your actual server address and port.

2. Open Swagger UI

Navigate to the Swagger UI in your web browser: http://localhost:42042/swagger/
The server automatically redirects the root URL (/) to the Swagger UI, so you can also simply visit: http://localhost:42042

Swagger UI

Swagger UI Interface Overview

Main Components

The Swagger UI interface consists of several key sections:

  1. API Information Header

    • API title and version
    • Server information
    • Base URL

  2. Endpoint Groups (Tags)

    • Organized by functionality (System, Lifecycle, Devices, etc.)
    • Collapsible sections for better navigation

  3. Individual Endpoints

    • HTTP method and path
    • Brief description
    • Parameters and response information

  4. Global Controls

    • Authorization settings
    • Server selection
    • Response format options

Exploring API Endpoints

Expanding Endpoint Groups

Click on any endpoint group to expand it and see the available operations.

Understanding HTTP Methods

Each endpoint shows its HTTP method with colour coding:

  • 🟢 GET (Green) - Retrieve data
  • 🔵 POST (Blue) - Create or trigger operations
  • 🟡 PUT (Yellow) - Update existing resources
  • đź”´ DELETE (Red) - Remove resources

Viewing Endpoint Details

Click on any individual endpoint to expand its details:

Open GET

Testing API Endpoints

Simple GET Request Example

Let's test the system version endpoint:

  1. Expand the System group and click on GET /v1/system/version

  2. Click "Try it out" button
    Try it out

  3. Click "Execute" to make the request
    Execute GET

The response will show:

  • Response Code (e.g., 200 for success)
  • Response Body with the actual data
  • Response Headers
  • Request URL that was called

GET response

POST Request with Parameters

Let's test initialising the lifecycle services:

  1. Expand the Lifecycle group and click on POST /v1/lifecycle/initialize
  2. Click "Try it out"
  3. Edit the request body in the text area:
{
  "dataDirectory": "C:\\ProgramData\\ElementsHub\\Data",
  "logDirectory": "C:\\ProgramData\\ElementsHub\\Logs"
}

POST with payload

  1. Click "Execute"

POST Request with Path Parameters

For endpoints that require path parameters:

  1. Expand Connected Devices and click on GET /v1/devices/{deviceId}
  2. Click "Try it out"
  3. Enter the device ID in the parameter field
  4. Click "Execute"

Understanding Request and Response Schemas

Request Body Schemas

When an endpoint accepts a request body, Swagger UI shows:

[SCREENSHOT MARKER: Request body schema showing expandable object structure with property types and descriptions]

  • Property names and their types
  • Required fields (marked with *)
  • Example values
  • Property descriptions

You can click on the schema to see more details and copy the example JSON.

Response Schemas

Each endpoint shows possible response codes and their schemas:

  • 200 Success responses with data structure
  • 400 Bad Request error format
  • 404 Not Found responses
  • Other status codes as applicable

Working with Different Content Types

Image Responses

Some endpoints return images (like device camera captures):

  1. Navigate to GET /v1/devices/{deviceId}/images/latest

  2. Select the appropriate Accept header (e.g., image/jpeg)

  3. Execute the request

The response will show the image data or provide a download link.

File Downloads

For endpoints that return files, Swagger UI will provide options to download or view the file content.

Error Handling and Debugging

Common Error Responses

When requests fail, Swagger UI displays helpful error information.

Request Validation Errors

If your request doesn't match the expected schema, Swagger UI will highlight:

  • Missing required fields
  • Invalid data types
  • Out-of-range values
  • Format violations

Network and Server Errors

For connectivity issues check:

  • Server is running
  • Correct URL and port
  • Network connectivity
  • Firewall settings

Advanced Features

Multiple API Versions

If multiple API versions are available, you can switch between them:

Server Selection

If multiple servers are configured, you can select which one to use:

Downloading OpenAPI Specification

You can download the raw OpenAPI specification:
Look for a link to download the swagger.json file for use with code generators.

Best Practices for Testing

1. Start with System Endpoints

Always begin by testing basic system endpoints:

  • GET /v1/system/version - Verify server is running
  • POST /v1/lifecycle/initialize - Initialize services

2. Follow the Logical Flow

For device operations, follow this sequence:

  1. Initialize lifecycle services
  2. Start a device scan
  3. Check available devices
  4. Connect to a device
  5. Perform device operations
  6. Disconnect when done

3. Check Dependencies

Some endpoints depend on others being called first:

  • Device operations require initialization.
  • Device connections require scanning.
  • Measurements require connected devices.

4. Use Realistic Test Data

When testing with sample data:

  • Use valid file paths for directory parameters.
  • Use realistic device identifiers.
  • Follow the expected data formats.

5. Monitor Response Times

Pay attention to response times for operations:

  • Some operations (like device scanning) may take time.
  • Check for appropriate timeout handling.
  • Consider async patterns for long-running operations.

Troubleshooting Common Issues

"Try it out" Button Not Working

  • Ensure JavaScript is enabled in your browser.
  • Check for browser console errors (press F12 on your keyboard).
  • Try refreshing the page.

CORS Errors

If testing from a different domain:

  • CORS may need to be configured on the server or proxy.
  • Try accessing from the same domain as the API.

Large Response Handling

For endpoints that return large amounts of data:

  • UI may slow down or freeze.
  • Responses may be truncated in the UI.
  • Consider using dedicated API clients for large data sets.
  • Check response size limits.

Integrating with Development Workflow

Documentation and Discovery

Use Swagger UI for:

  • API Documentation - Understanding available endpoints.
  • Schema Discovery - Learning request/response formats.
  • Quick Testing - Validating API behaviour.
  • Example Generation - Getting sample requests for development.

Code Generation Preparation

After exploring with Swagger UI:

  1. Download the OpenAPI specification.
  2. Use it with code generators (see chapter Client Code Generation).
  3. Reference the tested examples in your generated clients.

Tips for Effective API Exploration

1. Start Simple

Begin with read-only operations (GET requests) before attempting modifications.

2. Keep Notes

Document successful request patterns for later reference in your applications.

3. Test Edge Cases

Try invalid inputs to understand error handling and validation rules.

4. Understand State

Some operations change system state - be aware of the order of operations.

5. Use Browser Developer Tools

Monitor network requests in browser development tools for additional debugging information.