Rest API Overview

REST API Overview

CIB ins7ght exposes a REST API for accessing process analytics, statistics, and configuration data. All endpoints are accessible without authentication.

Base URL: http://localhost:8899 (configurable via server.port)

API Categories

1. Overview Statistics API

Base Path: /overview

Provides aggregated metrics and time-series data for process instances.

Endpoints:

• GET /overview - Get summary statistics
• GET /overview/graph/started-instances - Time series of started instances
• GET /overview/graph/finalized-instances - Time series of finalized instances
• GET /overview/graph/successful-instances - Time series of successful instances
• GET /overview/graph/canceled-instances - Time series of canceled instances
• GET /overview/graph/incident-instances - Time series of instances with incidents

View Details →

2. Process Analysis API

Base Path: /process-analysis

Provides detailed activity-level metrics, bottleneck detection, and outlier identification.

Endpoints:

• GET /process-analysis/activity - Activity-level statistics
• GET /process-analysis/activity-duration - Duration between activities
• GET /process-analysis/outliers - Outlier process instances
• GET /process-analysis/duration - Duration distribution
• GET /process-analysis/thresholds - Calculated outlier thresholds
• GET /process-analysis/version-duration - Version comparison statistics

View Details →

3. Process API

Base Path: /process

Provides access to process definitions, versions, and BPMN diagrams.

Endpoints:

• GET /process - List all process definitions
• GET /process/{processKey}/version - Get versions for a process
• GET /process/bpmn - Get BPMN XML diagram

View Details →

4. Info API

Base Path: /info

Provides application metadata and configuration.

Endpoints:

• GET /info - Get application version
• GET /info/properties - Get configuration properties

View Details →

5. Polling Info API

Base Path: /pollinfo

Provides polling status and data synchronization information.

Endpoints:

• GET /pollinfo - Get polling status and timestamps

View Details →

Quick Start

Get Application Version

curl -X GET "http://localhost:8899/info"

Get All Processes

curl -X GET "http://localhost:8899/process"

Get Overview Statistics

curl -X GET "http://localhost:8899/overview?processKey=invoice-process&version=1"

Get Activity Analysis

curl -X GET "http://localhost:8899/process-analysis/activity?processKey=invoice-process&version=1"

Check Polling Status

curl -X GET "http://localhost:8899/pollinfo"

Common Parameters

Most endpoints support the following query parameters for filtering:

Response Formats

JSON

Most endpoints return JSON data.

{
  "field": "value",
  "numericField": 123,
  "arrayField": [1, 2, 3]
}

Plain Text

The /info endpoint returns plain text.

0.0.2-SNAPSHOT 2025-01-29-1200

Binary (XML)

The /process/bpmn endpoint returns BPMN XML as binary data.

<?xml version="1.0" encoding="UTF-8"?>
<bpmn:definitions ...>
  ...
</bpmn:definitions>

Data Types

Timestamps

• Format: ISO 8601 with timezone (e.g., 2025-01-29T10:30:00Z)
• Unix Epoch: Long integers representing milliseconds since 1970-01-01 (e.g., 1704067200000)

Durations

• Format: Long integers representing milliseconds
• Example: 3600000 (1 hour)

Process Identifiers

• Process Key: String identifier for a process definition (e.g., invoice-process)
• Version: String representing version number (e.g., 1, 2)
• Process ID: Full process definition ID from CIB seven (e.g., invoice-process:1:abc123)

Error Handling

Successful Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": "..."
}

Error Response

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "timestamp": "2025-01-29T10:30:00.000+00:00",
  "status": 500,
  "error": "Internal Server Error",
  "message": "No Process Key provided",
  "path": "/process-analysis/activity"
}

Common Error Scenarios:

• Missing required parameters → 500 error with descriptive message
• Invalid process key/version → Empty array or null response
• Database connection issues → 500 error

CORS

CIB ins7ght does not configure CORS headers. If cross-origin access is required, configure CORS at the reverse proxy level.

Authentication

CIB ins7ght does not implement API authentication. All endpoints are publicly accessible.

Access control must be implemented through:

• Network-level security (firewalls, VPNs)
• Reverse proxy authentication
• Infrastructure security controls

See Security Instructions for details.

Rate Limiting

No rate limiting is implemented. Consider implementing rate limiting at the reverse proxy or infrastructure level if needed.

API Versioning

The REST API is not versioned. Breaking changes will be documented in release notes.

Testing the API

Using cURL

# Simple GET request
curl -X GET "http://localhost:8899/overview"

# With query parameters
curl -X GET "http://localhost:8899/overview?processKey=invoice-process&version=1&startDate=2025-01-01T00:00:00Z"

# Pretty print JSON response
curl -X GET "http://localhost:8899/overview" | jq .

Using Browser

Most GET endpoints can be accessed directly in a browser:

http://localhost:8899/process
http://localhost:8899/pollinfo
http://localhost:8899/info/properties

API Documentation by Category

1. Overview Statistics API - Aggregated metrics and time-series data
2. Process Analysis API - Activity analysis and bottleneck detection
3. Process API - Process definitions and BPMN diagrams
4. Info API - Application metadata and configuration
5. Polling Info API - Polling status and synchronization

Need Help?

• Check individual API documentation pages for detailed endpoint information
• Review JSON examples for expected request/response formats
• Consult Configuration Guide for server configuration
• See Troubleshooting for common issues