API docs by Redocly

BKN 知识网络 · 关系类 API (0.1.0)

Download OpenAPI specification:

Relation types use relation_type:{kn_id}/{relation_type_id}. Reads and lists require view_detail; data reads require query_data; updates and deletes use modify and delete. Lists and searches are filtered before total and pagination. See ../knowledge-network-authorization.md.

Resource IDs use lowercase letters, digits, underscores, and hyphens, start with a letter or digit, and contain at most 128 characters. Resource names contain at most 128 Unicode characters.

With strict_mode=true, indirect relation mappings read the backing Vega schema under the source contract's query_data operation; they do not introduce an implicit view_detail requirement. Main-branch publication reuses the effective delegator selected by Proxy preflight. Missing bindings return 400; a current-user denial returns 403; controlled lookup failures return 502, and timeout/unavailable dependencies return 503 without exposing the downstream response body.

List relation types

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

query Parameters
name_pattern
string

Fuzzy-match by relation type name. Empty by default.

sort
string
Enum: "update_time" "name"

Sort field. Defaults to update_time.

direction
string
Enum: "asc" "desc"

Sort direction. Supported values are asc and desc. Defaults to desc.

offset
integer <int64>

Offset of the first returned item. Must be greater than or equal to 0. Defaults to 0.

limit
integer <int64>

Maximum number of returned items per page. Supported paginated values are 1 to 1000; -1 disables pagination. Defaults to 10.

tag
string

Exact-match by tag. Empty by default.

source_object_type_id
string

Source object type ID

target_object_type_id
string

Target object type ID

bound_object_type_id
Array of strings

Bound object type ID. Finds relation types whose source or target equals this object type. Multiple values are supported.

branch
string
Default: "main"

Branch. Defaults to main.

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ],
  • "total_count": 0
}

Create or search relation types

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

query Parameters
branch
string
Default: "main"

Branch. Defaults to main.

import_mode
string
Default: "normal"
Enum: "normal" "overwrite" "ignore"

Import mode. normal returns an error for a concept with the same name; overwrite replaces it; ignore skips it. Defaults to normal.

confirm_clear_declarations
boolean
Default: false

With overwrite, a file that does not carry the BKN spec 3.0 declarations of an existing relation type, such as a 2.x package or an old JSON export, would clear them. Without this parameter the request is refused with 409 BknBackend.RelationType.DeclarationsWouldBeCleared, whose details list the cleared declarations (relation_type_id, fields); pass true to clear them.

strict_mode
boolean
Default: true

Whether to validate dependency existence. Defaults to true. When unset, falls back to the deprecated validate_dependency.

header Parameters
x-http-method-override
required
string
Enum: "POST" "GET"

Override request headers

Request Body schema: application/json
required
required
Array of objects (ReqRelationType)

Relation type details

Responses

Request samples

Content type
application/json
Example
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
Example
{
  • "entries": [
    ],
  • "total_count": 2,
  • "next_cursor": "cursor-relation-types-1"
}

Update a relation type

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

rt_id
required
string

Relation type ID

query Parameters
branch
string

Branch. Uses main when omitted.

strict_mode
boolean
Default: true

Whether to strictly validate dependencies. When true, validates dependencies such as related object types and data views. When false, skips this validation.

Request Body schema: application/json
required
name
required
string <= 128 characters

Name

tags
Array of strings

Tags used for business identification

comment
string

Comment

icon
string

Icon

color
string

Color

branch
required
string

Branch ID

source_object_type_id
string <= 128 characters ^[a-z0-9][a-z0-9_-]{0,127}$

Source object type ID

target_object_type_id
string <= 128 characters ^[a-z0-9][a-z0-9_-]{0,127}$

Target object type ID

type
string
Enum: "direct" "indirect" "filtered_cross_join"

Relation type

Array of DirectMappingRules (objects) or IndirectMappingRule (object) or FilteredCrossJoinMappingRule (object)

Associated matching rule. For direct, this is a Mapping array; for filtered_cross_join, this is a FilteredCrossJoinMappingRule.

reverse_name
string

BKN spec 3.0. The name of the relation read from the target to the source, with the rules of name. Empty is none.

aliases
Array of strings

BKN spec 3.0. Other names of the relation type. Empty is none.

cardinality
string
Enum: "one_to_one" "one_to_many" "many_to_one" "many_to_many"

BKN spec 3.0. How many counterparts an instance of each end has, from source to target. Empty is not declared; a filtered_cross_join relation can only be many_to_many.

object (RelationConstraints)

BKN spec 3.0. The Relation Constraints section of the relation type.

object (Lifecycle)

BKN spec 3.0. Whether the definition is still in use. Without it the definition is active. status deprecated needs a reason; replaced_by names an active definition of the same kind.

importance
string
Enum: "primary" "secondary"

BKN spec 3.0. primary (the default, returned as empty) or secondary.

fallback_for
string

BKN spec 3.0. On a secondary relation, the ID of the primary relation it stands in for when a source instance has no primary counterpart. Empty is none.

verification
string
Enum: "confirmed" "unconfirmed"

BKN spec 3.0. confirmed when the relation joins on real identifiers, unconfirmed when it joins by inferred rules. Empty is not declared.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "tags": [
    ],
  • "comment": "string",
  • "icon": "string",
  • "color": "string",
  • "branch": "string",
  • "source_object_type_id": "string",
  • "target_object_type_id": "string",
  • "type": "direct",
  • "mapping_rules": [
    ],
  • "reverse_name": "string",
  • "aliases": [
    ],
  • "cardinality": "one_to_one",
  • "constraints": {
    },
  • "lifecycle": {
    },
  • "importance": "primary",
  • "fallback_for": "string",
  • "verification": "confirmed"
}

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "description": "string",
  • "error_details": null,
  • "metadata": { }
}

Get relation type details

Authorizations:
OAuth2
path Parameters
rt_ids
required
Array of strings

Relation type ID

kn_id
required
string

Business knowledge network ID

query Parameters
branch
string
Default: "main"

Branch. Defaults to main.

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ]
}

Delete relation types

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

rt_ids
required
Array of strings

Relation type ID

query Parameters
branch
string
Default: "main"

Branch. Defaults to main.

Responses

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "description": "string",
  • "error_details": null,
  • "metadata": { }
}

Explore concept paths from a source

Explore concept paths from a source

Authorizations:
OAuth2
path Parameters
kn_id
required
any
query Parameters
branch
string
Default: "main"

Branch. Defaults to main.

header Parameters
x-http-method-override
required
string
Value: "GET"

Must be GET. The request is sent as POST so the query can be carried in the body.

Request Body schema: application/json
required
concept_groups
Array of strings

Concept group ID array

source_object_type_id
required
string

Source object type ID

path_length
required
integer

Path length. Must not exceed 3.

direction
required
string
Enum: "forward" "backward" "bidirectional"

Direction: forward, backward, or bidirectional.

Responses

Request samples

Content type
application/json
{
  • "source_object_type_id": "comment",
  • "direction": "backward",
  • "path_length": 1
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Validate relation types

Validates relation type dependency existence only and does not write data. It verifies dependencies such as source and target object types and indirect data views.

Response: HTTP 200 uses valid and detail for ordinary model validation. Strict dependency failures return the documented 400/403/502/503 error envelope, whose error_details includes a safe dependency_kind.

Internal API: POST /api/bkn-backend/in/v1/.../relation-types/validation. The caller is resolved from headers and OAuth is not required.

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

query Parameters
branch
string

Branch. Uses main when omitted.

strict_mode
boolean
Default: true

Whether to strictly validate dependencies. Defaults to true.

import_mode
string
Default: "normal"
Enum: "normal" "ignore" "overwrite"

Same as the create relation type API. Defines validation semantics for existing relation type ID conflicts; name conflicts follow create behavior.

confirm_clear_declarations
boolean
Default: false

With overwrite, a file that does not carry the BKN spec 3.0 declarations of an existing relation type, such as a 2.x package or an old JSON export, would clear them. Without this parameter the request is refused with 409 BknBackend.RelationType.DeclarationsWouldBeCleared, whose details list the cleared declarations (relation_type_id, fields); pass true to clear them.

Request Body schema: application/json
required
entries
Array of objects

Relation type list to validate. Its structure is the same as the create API.

Responses

Request samples

Content type
application/json
{
  • "entries": [
    ]
}

Response samples

Content type
application/json
{
  • "valid": true,
  • "detail": "string"
}