API Developer Guide

This document is for developers who need to integrate or extend the Huayang CMDB system through APIs. It introduces the Huayang CMDB REST API design specifications, authentication methods, request/response formats, and API module overviews.

Basic Conventions

URL Structure

All APIs follow a unified URL pattern:

{base_url}/api/{tenantId}/cmdb/{module}/{resource}

Part	Description	Example
`base_url`	API server address	`http://localhost:8102/itom`
`tenantId`	Tenant ID (path parameter)	`100000001`
`module`	Module name	`class-model`, `tql-query`, `datain`
`resource`	Resource path	`definitions`, `definitions/{name}`

HTTP Method Semantics

Method	Semantics	Idempotent
`GET`	Query resources	Yes
`POST`	Create resources or execute actions	No
`PUT`	Update resources (full replacement)	Yes
`DELETE`	Delete resources	Yes

Request Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer {access_token}

Authentication

The system uses Keycloak as the identity authentication service. Calling protected APIs requires obtaining an access token first.

Obtain Token

POST /api/{tenantId}/platform/authenticate

Request body:

{
  "username": "admin",
  "password": "admin"
}

Success response (200):

{
  "success": true,
  "code": 200,
  "timestamp": "2026-04-15T10:30:00.000Z",
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 300,
    "refresh_expires_in": 1800
  }
}

Authentication failure (401):

{
  "success": false,
  "code": 401,
  "timestamp": "2026-04-15T10:30:00.000Z",
  "error": {
    "errorcode": "15010401",
    "message": "Invalid username or password",
    "type": "AUTHENTICATION_ERROR",
    "details": {}
  }
}

Using the Token

Include the token in subsequent requests via the Authorization header:

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Unified Response Format

All API responses follow a unified envelope format containing success, code, and timestamp as required fields.

Success Response

{
  "success": true,
  "code": 200,
  "timestamp": "2026-04-10T07:28:33.695Z",
  "data": { ... }
}

Error Response

{
  "success": false,
  "code": 400,
  "timestamp": "2026-04-10T07:28:33.695Z",
  "error": {
    "errorcode": "15010400",
    "message": "Validation failed",
    "type": "VALIDATION_ERROR",
    "details": { ... }
  }
}

Error Code Structure

Error codes are 8-digit numbers composed of three parts:

{serviceCode}{moduleCode}{errorCode}

Component	Description	Example
Service code (2 digits)	Identifies the source service	`15` = cmdb-api, `20` = class-model
Module code (2 digits)	Identifies the module	`01` = classModel, `02` = tqlQuery, `03` = datain
Error code (4 digits)	Specific error	`0400` = validation failed, `0404` = not found

Error Types

type	HTTP Status	Description
`VALIDATION_ERROR`	400	Request parameter validation failed; `details` contains specific field errors
`AUTHENTICATION_ERROR`	401	Not authenticated or invalid token
`AUTHORIZATION_ERROR`	403	Insufficient permissions
`NOT_FOUND_ERROR`	404	Requested resource does not exist
`CONFLICT_ERROR`	409	Resource conflict (e.g., duplicate creation)
`RATE_LIMIT_ERROR`	429	Request rate limit exceeded
`INTERNAL_SERVER_ERROR`	500	Internal server error

Query Parameters

List endpoints support unified query parameters:

Parameter	Type	Default	Description
`limit`	integer	20	Number of records per page (1-1000)
`offset`	integer	0	Offset
`sort`	array	-	Sort conditions `[{field, direction}]`
`fields`	array	-	Return field whitelist
`filters`	array	-	Filter conditions (see below)

API Module Overview

Class Model — CI Type Management

CRUD operations and inheritance hierarchy management for CI types (Class Definitions).

Method	Path	Description
GET	`/class-model/definitions`	Get all class definitions
POST	`/class-model/definitions`	Create a class definition
GET	`/class-model/definitions/{name}`	Get a specific class definition
PUT	`/class-model/definitions/{name}`	Update a class definition
DELETE	`/class-model/definitions/{name}`	Delete a class definition
GET	`/class-model/definitions/{name}/parents`	Get parent class list
GET	`/class-model/definitions/{name}/children`	Get child class list
GET	`/class-model/definitions/{name}/hierarchy`	Get full hierarchy

Core Class Definition Fields:

{
  "name": "ci_server",
  "display_name": "Server",
  "parent_name": "ci_host",
  "description": "Server CI type",
  "attributes": {
    "ip_address": {
      "name": "ip_address",
      "type": "string",
      "required": false,
      "display_name": "IP Address"
    }
  },
  "identification_rule": {
    "attributes": ["serial_number"]
  }
}

Query Parameters:

includeAttributes (boolean) — Whether to include attribute definitions in the response
includeMetadata (boolean) — Whether to include metadata
parentDepth / childDepth (integer) — Depth for hierarchy queries

Datain — Data Write

Unified data write entry point, supporting simultaneous CI and relationship operations in a single request.

POST /datain/topology

Operation types (operation field):

add — Add nodes and relationships
update — Update existing nodes
delete — Delete nodes or relationships
addOrUpdate — Update if exists, add if not

Request example:

{
  "operation": "add",
  "nodes": [
    {
      "id": "server-001",
      "type": "ci_server",
      "properties": {
        "name": "web-server-01",
        "ip_address": "192.168.1.10"
      }
    }
  ],
  "links": [
    {
      "id": "link-001",
      "type": "r_runs_on",
      "from_id": "server-001",
      "to_id": "app-001"
    }
  ]
}

The id in nodes is a client-side temporary identifier. The system returns the actual ID after processing. links reference node temporary IDs via from_id/to_id to establish relationships.

TQL Query — Topology Query

Execute TQL (Topology Query Language) queries for cross-type querying of CIs and their relationship data.

POST /tql-query/execute

Core request structure concepts:

{
  "tqlQuery": {
    "type": "normal",
    "rootNode": "ci_computer",
    "limit": 20,
    "nodes": [
      {
        "type": "ci_computer",
        "queryIdentifier": "computer",
        "visible": true,
        "typeConfig": {
          "includeSubtypes": true
        },
        "layoutConfig": {
          "type": "SIMPLE",
          "items": ["name", "ip_address"]
        },
        "attributeConditions": [
          {
            "attribute": "name",
            "operator": "contains",
            "value": "server"
          }
        ],
        "linkConditions": [
          {
            "linkIdentifier": "runs_on",
            "conditionType": "exists"
          }
        ]
      }
    ],
    "relations": [
      {
        "type": "r_runs_on",
        "queryIdentifier": "runs_on",
        "from": "computer",
        "to": "app",
        "linkType": "normal"
      }
    ],
    "orderBy": [{ "field": "id", "direction": "ASC" }]
  }
}

Top-level Fields:

Field	Description
`type`	Query type, currently fixed as `normal`
`rootNode`	Root CI type name for the query
`nodes`	List of CI type nodes in the query
`relations`	Relationship definitions between nodes
`orderBy`	Sort configuration, format `[{field, direction}]`, direction options: `ASC` / `DESC`
`limit`	Return count limit

TQL Operators:

Operator	Description
`equals`	Equals
`notEquals`	Not equals
`greaterThan`	Greater than
`greaterThanOrEqual`	Greater than or equal
`lessThan`	Less than
`lessThanOrEqual`	Less than or equal
`in`	In list
`notIn`	Not in list
`isNull`	Is null (`value: true` = IS NULL, `value: false` = IS NOT NULL)
`like`	Fuzzy match
`contains`	Contains
`startsWith`	Starts with
`endsWith`	Ends with
`containsAny`	Contains any (array)
`containsAll`	Contains all (array)
`containsIgnoreCase`	Contains (case insensitive)

Pagination: When hasMore is true in the response, use the cursor value to continue querying for subsequent data.

Query Definition — Query Definition Management

Manage reusable TQL query definitions.

Method	Path	Description
GET	`/query-definition/definitions`	Get all query definitions
POST	`/query-definition/definitions`	Create a query definition
GET	`/query-definition/definitions/{name}`	Get a specific query definition
PUT	`/query-definition/definitions/{name}`	Update a query definition
DELETE	`/query-definition/definitions/{name}`	Delete a query definition
GET	`/query-definition/query-groups`	Get query group list
POST	`/query-definition/query-groups`	Create a query group
PUT	`/query-definition/query-groups/{id}`	Update a query group
DELETE	`/query-definition/query-groups/{id}`	Delete a query group
GET	`/query-definition/query-groups/{groupId}/definitions`	Get query definitions under a group

Query parameter: includeDefinition (boolean) — List endpoints don't return query definition content by default; set to true to include it.

CI History — CI Change History

Query CI change records.

Method	Path	Description
GET	`/ci-history`	Query change history list
GET	`/ci-history/entity/{entityId}/{entityType}`	Query change history for a specific CI
GET	`/ci-history/transaction/{transactionId}`	Query change details for a specific transaction

Relation History — Relationship Change History

Query CI relationship change records.

Method	Path	Description
GET	`/relation-history`	Query relationship change history list
GET	`/relation-history/from/{fromId}/to/{toId}`	Query change history between two CIs

CI Export — CI Export

Asynchronous export of CI data.

Method	Path	Description
POST	`/ci-export/list`	Submit an export task
GET	`/ci-export/{jobId}/status`	Query export task status

Export is an asynchronous operation. After submission, a jobId is returned. Poll the status endpoint to get progress and download link.

Dashboard — Dashboard Management

Manage dashboards and their groups.

Dashboard API supports CRUD operations, group management, import/export, and more. System-preset dashboards have protection markers and cannot be edited or deleted.

Swagger Documentation

The system includes built-in Swagger UI. After deployment, you can find the API documentation entry in the navigation menu to view the complete API specification, request examples, and online debugging directly in the browser.

Basic Conventions​

URL Structure​

HTTP Method Semantics​

Request Headers​

Authentication​

Obtain Token​

Using the Token​

Unified Response Format​

Success Response​

Error Response​

Error Code Structure​

Error Types​

Query Parameters​

API Module Overview​

Class Model — CI Type Management​

Datain — Data Write​

TQL Query — Topology Query​

Query Definition — Query Definition Management​

CI History — CI Change History​

Relation History — Relationship Change History​

CI Export — CI Export​

Dashboard — Dashboard Management​

Swagger Documentation​