# Synonyms

Very often integrating parties refer to the same catalog item by different names, for example a product might be called "Gas" by one party and "Gasoline" by another. When both parties independently submit documents to the integration workspace, they are likely to create multiple catalog records describing the same thing. Since integration process is essentially a process of reaching data consistency between all parties involved, it becomes very important to be able to combine duplicate catalog records. Catalog synonyms API provides users with the tool to do so.

Catalog synonyms are links between two catalog records, allowing the user to associate their version of a catalog item to the version of their integration counterparty.

# Data Model

All entities used for this API follow canonical Entity Envelope data format. Below is the synonym record body schema.

Field Type Description
workspace UUID Reference to the parent workspace.
baseItem UUID Reference to one of the linked items.
linkedItem UUID Reference to the other linked item.

Note: there is no semantic difference between baseItem and linkedItem fields. The words base and linked in the names are there only for backward compatibility and will be removed in a future version of the API.

# Example Body

{
    "workspace": "a2070b04-ca32-4a36-af58-c56e25715cb5",
    "baseItem": "ee65efca-ca16-4a88-a85f-a8559c577760",
    "linkedItem": "ee65efca-ca16-4a88-a85f-a8559c577760"
}

# Search Synonyms

GET /v2/workspaces/:workspaceId/synonyms

# Request parameters

Parameter Description Type Required Default
workspace_id Workspace ID UUID yes
limit Maximum number of records to return integer no 25
offset The number of records to skip integer no 0
sort List of comma-separated ordering criteria string: field:asc|desc no "created_at:desc, id:asc"
xtype Catalog type to filter the synonym records by string no

# Request body

None

# Response

An array of entity envelopes with the type set to navarik.bridge.synonym and the body formatted to the synonym.

# Find Synonyms for External Reference Record

GET /v2/workspaces/:workspaceId/xrefs/:xtype/:xref_id/synonyms

# Request parameters

Parameter Description Type Required Default
workspace_id Workspace ID UUID yes
xtype Catalog type. string yes
xref_id External reference record ID. UUID yes
limit Maximum number of records to return integer no 25
offset The number of records to skip integer no 0
sort List of comma-separated ordering criteria string: field:asc|desc no "created_at:desc, id:asc"

# Request body

None

# Response

An array of entity envelopes with the type set to navarik.bridge.synonym and the body formatted to the synonym.

# Create Synonym

POST /v2/workspaces/:workspaceId/xrefs/:xtype/:xref_id/synonyms/:linked_item_id

# Request parameters

Parameter Description Type Required Default
workspace_id Workspace ID UUID yes
xtype Catalog type. string yes
xref_id External reference record ID. UUID yes
linked_item_id Linked external reference record ID. UUID yes

# Request body

None

# Response

An single entity envelope with the type set to navarik.bridge.synonym and the body formatted to the synonym.

# Delete Synonym

DELETE /v2/workspaces/:workspaceId/xrefs/:xtype/:xref_id/synonyms/:linked_item_id

# Request parameters

Parameter Description Type Required Default
workspace_id Workspace ID UUID yes
xtype Catalog type. string yes
xref_id External reference record ID. UUID yes
linked_item_id Linked external reference record ID. UUID yes

# Request body

None

# Response

Last known version of the deleted synonym as a single entity envelope with the type set to navarik.bridge.synonym and the body formatted to the synonym.

← Inspection Worksheet →