Part relations

Part relations allow you to establish connections between parts in your catalog. These relations can be used to indicate duplicates, substitutes, or equivalent parts.

Part relations can be created by authorized users or ingested from your catalog data sources.

Relation types

The following relation types are supported:

• duplicate: Indicates that the parts are a duplicated entry in the catalog. They should have never entered the system of record.
• substitute: Indicates that one part can be used as a substitute for another. This is the case of successors or predecessors. They are meant to be part of the catalog as a result of obsolescence management. Whether one part is the successor or the predecessor of the other depends on how the relation is created (see Create relations).
• equivalent: Indicates that the parts can be used interchangeably despite being typically produced by a different manufacturer or maybe have slightly different specifications.
• not_related: Indicates that the parts do not have any of the other possible relations. This type of relation is used for cases were (a) there was a previously erroneously relation set (see Removing part relations) or (b) when comparing parts that have certain similarity, to confirm that they cannot be considered an alternative part.

Relation sources

Relations can come from two sources:

• confirmed_by_user: Relations that have been manually confirmed by a user
• ingested: Relations that were automatically ingested from data sources

Get relations by type

Get all relations of a specific type for a given part.

GET /v1/parts/{part_id}/relations/{relation_type}

Parameters

Name	Type	In	Description
part_id	string	path	Required. ID of the part to get relations for
relation_type	string	path	Required. Type of relations to get. Must be one of: duplicate, substitute, equivalent, not_related

Response

Returns a list of part relations. Each relation includes:

[
  {
    "part_id": "string",
    "part_role": "string",
    "type": "string",
    "source": "string",
    "user_id": "string",
    "created": "datetime"
  }
]

Field	Type	Description
part_id	string	ID of the part in the relation
part_role	string	Role of the part in the relation (anchor_part or related_part)
type	string	Type of relation (duplicate, substitute, equivalent, not_related)
source	string	Source of the relation (confirmed_by_user or ingested)
user_id	string	ID of the user who created the relation (optional)
created	datetime	Timestamp when the relation was created

Error responses

Status Code	Description
400	Invalid request parameters
401	Unauthorized
404	Part not found
500	Internal server error

Create relations

Create new relations between parts in bulk.

POST /v1/parts/relations

note

This endpoint will respond with error code 503 when the catalog API is in maintenance mode.

Request body

The request body should contain a list of part relations to create:

[
  {
    "anchor_part_id": "string",
    "related_part_id": "string",
    "type": "string",
    "source": "string"
  }
]

Field	Type	Description
anchor_part_id	string	Required. ID of the anchor part. For substitute relations, this identifies the predecessor part.
related_part_id	string	Required. ID of the related part. For substitute relations, this identifies the successor part.
type	string	Required. Type of relation (duplicate, substitute, equivalent, not_related). In the case of substitute, the part identified by anchor_part_id is the predecessor of the one identified by related_part_id, and the successor relation is automatically defined in the opposite sense.
source	string	Source of the relation (confirmed_by_user or ingested). Defaults to ingested

Error responses

Status Code	Description
400	Invalid request body
401	Unauthorized
403	Permission denied
500	Internal server error

Removing part relations

Part relations are automatically removed when a part is deleted. All relations where the deleted part is either the anchor or related part are removed.

Relations are considered based on the latest update to a relation between a pair of parts. As a consequence, there is no explicit API endpoint to delete individual relations. Instead, manage relations by:

1. creating new relations with updated information;
2. marking parts as not_related if they were incorrectly related; or
3. removing the parts if they should no longer exist in the catalog.

Examples

Get duplicate relations for a part

GET /v1/parts/PART123/relations/duplicate

Response:

[
  {
    "part_id": "PART456",
    "part_role": "related_part",
    "type": "duplicate",
    "source": "confirmed_by_user",
    "user_id": "USER789",
    "created": "2024-03-14T12:00:00Z"
  }
]

Create multiple relations

POST /v1/parts/relations

[
  {
    "anchor_part_id": "PART123",
    "related_part_id": "PART456",
    "type": "duplicate"
  },
  {
    "anchor_part_id": "PART789",
    "related_part_id": "PART012",
    "type": "substitute",
    "source": "confirmed_by_user"
  }
]