External Synchronization API Reference

info

This reference is for developers and integration engineers implementing an external synchronization endpoint. It defines pagination, topology models, node and edge constraints, and interface-to-service drill-down bindings. For the setup workflow, complete Synchronize External Business Traces first.

Prerequisites

Provide an HTTP API that ONE can access from its deployment environment.
Configure the external synchronization URL in ONE. If authentication is required, configure network access and authentication as agreed for the deployment.
Assign a stable unique ID to every topology and node. The same object must return the same ID in every synchronization batch.
To support drill-down from an interface topology to a service subgraph, prepare a matching interface topology, service topology, and relationBindings data.

API Request

Method

POST /api/topology/list HTTP/1.1
Content-Type: application/json

/api/topology/list is the path used in this protocol example. Use the URL configured for the deployment.

Request Body

{
  "pageNo": 1,
  "pageSize": 1000,
  "uniqueTopologys": ["APPRegist-interface", "APPRegist-service"],
  "topologyName": "APP"
}

Field	Type	Required	Description
`pageNo`	Integer	No	Page number, starting at `1`. The default is `1`.
`pageSize`	Integer	No	Number of topologies per page. Support a value of `1000`; preview and apply operations commonly fetch `1000` records per page.
`uniqueTopologys`	String[]	No	Exact-match filter for external topology IDs. An empty array, `null`, or an omitted field means no ID filtering.
`topologyName`	String	No	Fuzzy-match filter for the topology name.

API Response

Response Wrapper

{
  "code": "200",
  "msg": "success",
  "data": {
    "totalRecord": 40000,
    "pageNo": 1,
    "pageSize": 1000,
    "results": []
  }
}

Field	Type	Required	Description
`code`	String	Yes	Response code. `"200"` indicates success.
`msg`	String	Yes	Response message. A successful response can return `"success"`.
`data`	Object	Yes	Pagination data.
`data.totalRecord`	long	Yes	Total number of filtered topology slots. Interface and service topologies each count as one record.
`data.pageNo`	int	Yes	Current page number. It must match the requested page.
`data.pageSize`	int	Yes	Current page size.
`data.results`	TopologyItem[]	Yes	Topologies on the current page. Return `[]` when the page has no data.

TopologyItem

Each element in data.results represents one independently synchronized topology.

Field	Type	Required	Description
`uniqueTopology`	String	Yes	Globally unique and stable external topology ID, such as `APPRegist-interface`.
`topologyName`	String	Yes	Display name shown in ONE.
`updateTime`	String	Yes	Source-side modification time. If the source cannot provide a reliable value, always return an empty string `""` so ONE fetches and compares the source data on every synchronization.
`nodes`	NodeItem[]	Yes	Nodes in the topology. Return `[]` when empty.
`edges`	EdgeItem[]	Yes	Edges in the topology. Return `[]` when empty. Every edge must include all four reference fields.
`relationBindings`	RelationBindingItem[]	Yes	Interface-to-service drill-down relationships. Return `[]` when there is no binding. Do not return `null` or omit the field.

NodeItem

Field	Type	Required	Description
`uniqueNode`	String	Yes	External identifier unique within the same `nodeType`. Construct it according to the CMDB instance uniqueness rules below. ONE uses it to look up the instance and obtain its instance ID. It may contain a pipe character (`\|`).
`nodeName`	String	Yes	Node display name.
`nodeType`	String	Yes	ONE `modelKey`, such as `interface` or `service`. It must not contain a pipe character (`\|`).

A node is uniquely identified by the combination of nodeType and uniqueNode. Nodes of different types can therefore use the same uniqueNode.

Mapping `uniqueNode` to a CMDB Instance

ONE uses nodeType to identify the corresponding CMDB entity model, then queries an instance by matching uniqueNode against that model's instance uniqueness rule. After a match, ONE obtains and associates the CMDB instance ID.

Entity model	Default `uniqueNode` construction rule	Default unique identifier
Service (`service`)	`${detectedName}`	Service detected name.
Interface (`interface`)	`${detectedName}_${interfaceType}_${service.detectedName}`	Interface detected name + interface type + parent service ID.

warning

The table lists the default instance uniqueness rules for the service and interface models. Do not use an arbitrary business ID unrelated to the CMDB instance as uniqueNode. If a CMDB model's uniqueness rule has been customized in ONE, construct the value according to the actual configuration. Field values, letter case, and underscore separators must match exactly; otherwise, ONE cannot associate the instance or obtain its instance ID.

EdgeItem

Field	Type	Required	Description
`fromNodeType`	String	Yes	Source node type. It must match the source node's `nodeType`.
`fromUniqueNode`	String	Yes	Source node ID. The referenced node must exist in this topology's `nodes`.
`toNodeType`	String	Yes	Target node type. It must match the target node's `nodeType`.
`toUniqueNode`	String	Yes	Target node ID. The referenced node must exist in this topology's `nodes`.

warning

Every edge must provide fromNodeType, fromUniqueNode, toNodeType, and toUniqueNode. The legacy two-field format that contains only the source and target IDs is discarded and produces an incomplete topology.

RelationBindingItem

relationBindings describes which service nodes and edges are displayed when a user drills down from an interface node.

Field	Type	Required	Description
`sourceUniqueTopology`	String	Yes	ID of the interface topology containing the drill-down entry node.
`sourceNodeType`	String	Yes	Entry node type. Use `interface` for an interface topology. The value must not contain a pipe character (`\|`).
`sourceUniqueNode`	String	Yes	`uniqueNode` of the entry node. It must match a node in the referenced interface topology.
`associatedNodes`	NodeRefItem[]	Yes	References to nodes in the current service topology. Return `[]` when empty.
`associatedEdges`	EdgeItem[]	Yes	References to edges in the current service topology. Return `[]` when empty.

Each associatedNodes element uses the following structure:

Field	Type	Required	Description
`nodeType`	String	Yes	Associated node type, such as `service`.
`uniqueNode`	String	Yes	ID of the associated node in the service topology.

warning

associatedNodes must be an object array, for example [ {"nodeType":"service","uniqueNode":"node-A"} ]. Do not use a string array such as ["node-A"]; it can cause deserialization to fail or produce an empty binding.

Complete JSON Example

The following response returns matching interface and service topologies for the same business function. The interface node W12001214 is bound to a service subgraph, allowing users to drill down to the associated service nodes and edge.

{
  "code": "200",
  "msg": "success",
  "data": {
    "totalRecord": 40000,
    "pageNo": 1,
    "pageSize": 1000,
    "results": [
      {
        "uniqueTopology": "APPRegist-interface",
        "topologyName": "Mobile Number Registration - Function Topology",
        "updateTime": "",
        "nodes": [
          {
            "uniqueNode": "APPRegist",
            "nodeName": "Mobile Number Registration",
            "nodeType": "interface"
          },
          {
            "uniqueNode": "W12001214",
            "nodeName": "Mobile Number Validation and Activation",
            "nodeType": "interface"
          }
        ],
        "edges": [
          {
            "fromNodeType": "interface",
            "fromUniqueNode": "APPRegist",
            "toNodeType": "interface",
            "toUniqueNode": "W12001214"
          }
        ],
        "relationBindings": []
      },
      {
        "uniqueTopology": "APPRegist-service",
        "topologyName": "Mobile Number Registration - Component Topology",
        "updateTime": "",
        "nodes": [
          {
            "uniqueNode": "node11723473851691",
            "nodeName": "node11723473851691",
            "nodeType": "service"
          },
          {
            "uniqueNode": "node01636960691574",
            "nodeName": "node01636960691574",
            "nodeType": "service"
          }
        ],
        "edges": [
          {
            "fromNodeType": "service",
            "fromUniqueNode": "node11723473851691",
            "toNodeType": "service",
            "toUniqueNode": "node01636960691574"
          }
        ],
        "relationBindings": [
          {
            "sourceUniqueTopology": "APPRegist-interface",
            "sourceNodeType": "interface",
            "sourceUniqueNode": "W12001214",
            "associatedNodes": [
              {
                "nodeType": "service",
                "uniqueNode": "node11723473851691"
              },
              {
                "nodeType": "service",
                "uniqueNode": "node01636960691574"
              }
            ],
            "associatedEdges": [
              {
                "fromNodeType": "service",
                "fromUniqueNode": "node11723473851691",
                "toNodeType": "service",
                "toUniqueNode": "node01636960691574"
              }
            ]
          }
        ]
      }
    ]
  }
}

Follow these pairing rules:

An interface topology always returns relationBindings: [].
A service topology uses relationBindings to describe drill-down relationships from interface nodes to service subgraphs.
One service topology can contain multiple bindings for different interface nodes.
associatedNodes and associatedEdges may reference only data already present in the current service topology's nodes and edges.
Return nodeType and uniqueNode as separate fields. Do not prepend internal composite strings such as service| or interface| to uniqueNode.

Common Data Patterns

Pattern	How to represent it
Parallel root services	Return the service nodes in `nodes`; set both the topology `edges` and binding `associatedEdges` to `[]` when no ordering relationship exists.
Pipe character in `uniqueNode`	Values such as `svc
Same ID across node types	`service/pay` and `interface/pay` are distinct nodes because node identity includes both `nodeType` and `uniqueNode`.
Multiple interface entry nodes	Add one `relationBindings` element for each interface node and reference the service subgraph associated with that entry node.

Validation Rules

ONE validates relationBindings before applying synchronized data.

ID	Rule	Result when invalid
C1	Every NodeRef in `associatedNodes` must exist in the current service topology's `nodes`.	ONE discards the invalid reference and records a warning. If apply validation fails, the topology is added to `failedIds`.
C2	Every edge in `associatedEdges` must exist in the current service topology's `edges`, with all four fields matching.	ONE discards the invalid edge and records a warning. If apply validation fails, the topology is added to `failedIds`.
C3	`sourceNodeType` must not contain a pipe character (`\|`).	ONE discards the entire binding and records a warning.
C4	`sourceUniqueNode` must match a node in the interface topology identified by `sourceUniqueTopology`.	The drill-down entry is misplaced and cannot display the intended service subgraph.

Unsupported or Legacy Formats

Scenario	Invalid data	Result
Edge without node types	Only `fromUniqueNode` and `toUniqueNode` are returned.	The edge is discarded and the topology may be incomplete.
String array in `associatedNodes`	`"associatedNodes": ["node-A"]`	Deserialization can fail or the binding cannot be created.
Missing `sourceNodeType`	The field is omitted from a binding.	The entire binding is discarded.
Duplicate node or edge references	The same key appears more than once.	ONE deduplicates the data and records a warning.
Edge endpoint missing from `nodes`	An edge references an undeclared node.	The edge is discarded and the topology may be incomplete.

Integration Checklist

Before a full synchronization, test with a small data set and verify the following:

Confirm that a successful response returns the string "200" in code and that pagination metadata matches the request.
Confirm that totalRecord is the total filtered topology count, not the current page size or business function count.
Confirm that all empty list fields return [], especially nodes, edges, and relationBindings.
Confirm that every uniqueNode follows the corresponding CMDB model's instance uniqueness rule and resolves to an instance ID.
Confirm that every edge contains all four fields and references nodes declared in the current topology.
Confirm that matching interface and service topologies use different, stable uniqueTopology values.
Confirm that every binding references only nodes and edges in the current service topology.
Confirm that page ordering and data remain stable during one synchronization task to prevent duplicate or missing records.

tip

During initial integration, use uniqueTopologys to return only one matching interface/service pair. After verifying nodes, edges, and drill-down behavior, expand the synchronization scope.

warning

External data synchronization can take a long time. Wait for the current task to finish before starting another one.
Do not leave the page or refresh the browser while synchronization is running.
Each account can run only one synchronization task at a time.
If a reliable updateTime is unavailable, always return an empty string. Do not return the current request time because it changes on every call.

Prerequisites​

API Request​

Method​

Request Body​

API Response​

Response Wrapper​

TopologyItem​

NodeItem​

Mapping uniqueNode to a CMDB Instance​

EdgeItem​

RelationBindingItem​

Complete JSON Example​

Common Data Patterns​

Validation Rules​

Unsupported or Legacy Formats​

Integration Checklist​

Prerequisites

API Request

Method

Request Body

API Response

Response Wrapper

TopologyItem

NodeItem

Mapping `uniqueNode` to a CMDB Instance

EdgeItem

RelationBindingItem

Complete JSON Example

Common Data Patterns

Validation Rules

Unsupported or Legacy Formats

Integration Checklist