Add Relation

API Name

API Name: Element – Add Relation

---

Overview

This API creates a relation from a source element to a target element.

MBSE Core uses this API to:

• Establish structural relationships

• Create dependencies

• Create realizations

• Create associations and other modeling links

Connector responsibility:

• For the given elementId and context:

  • Create a relation in the end system.

• If the end system treats relations as elements:

  • No special implementation may be required beyond standard element creation.

• If the end system represents relations as separate relation elements:

  • Connector may need multiple API calls.

  • Create relation element.

  • Set relation properties or tagged values if required.

• Convert request into end system-specific relation format.

---

API URI

POST: /mbse/api/1.0/elements/{elementId}/relations
    ?projectId={projectId}
    &elementTypeId={elementTypeId}
    &branchId={branchId}

---

Path Parameters

Name	Mandatory	Type	Description
elementId	True	String	ID of the source element in the relation.

---

URI Parameters

Name	Mandatory	Type	Description
projectId	True	String	ID of the project.
elementTypeId	True	String	ID of the element type of the source element.
branchId	False	String	ID of the branch. If omitted, default branch behavior applies.

---

Request Body

{
  "relationType": "dependency",
  "targetElementId": "requirement_55",
  "targetElementTypeId": "Requirement"
}

---

Request Body Parameters

Name	Mandatory	Type	Description
relationType	True	String	Type of relation (association, dependency, generalization, realization, etc.).
targetElementId	True	String	ID of the target element.
targetElementTypeId	True	String	ID of the target element type.

---

Behavior Rules

1. The source element must exist within:

   • projectId

   • elementTypeId

   • Optional branchId

2. The target element must exist within the same project (unless cross-project relations are supported).

3. Only one relation must be created per request.

4. Connector must:

   • Call the appropriate end system API to establish the relation.

5. If the relation already exists:

   • Either ignore gracefully or return 409 Conflict depending on end system behavior.

6. If source or target element does not exist:

   • Return HTTP 404 Not Found.

---

Response

This API does not return a response body.

Successful Creation

HTTP Status: 201 Created or 204 No Content

---

Error Handling

HTTP Status	Description
400	Invalid input parameters.
404	Source or target element not found.
409	Relation already exists or constraint violation.
500	Internal server error during relation creation.

---

Example Use Case

Add Dependency Relation

POST /mbse/api/1.0/elements/block_200/relations?
projectId=123
&elementTypeId=Block

Request Body:

{
  "relationType": "dependency",
  "targetElementId": "requirement_55",
  "targetElementTypeId": "Requirement"
}

---

Implementation Guidelines

• Validate source element existence before relation creation.

• Validate target element existence before relation creation.

• Ensure branch consistency.

• If relation requires additional metadata:

  • Create relation.

  • Then update additional properties/tags.

• Avoid duplicate relation creation.

• Keep implementation idempotent if possible.

---

Design Considerations

Different MBSE systems model relations differently:

Case 1: Relation is implicit

• System directly supports linking elements.

• Single API call required.

Case 2: Relation is a separate element

• Create relation element.

• Set relation attributes.

• Associate source and target elements.

Connector must abstract these differences and always return consistent behavior.

---

Design Rationale

This API ensures:

• Controlled relation establishment

• System-agnostic modeling

• Clear source-target mapping

• Flexible implementation for heterogeneous MBSE tools

By isolating relation creation into a dedicated API, the integration layer remains clean, predictable, and extensible.