Understanding IDs and Refs in GraphQL Entities

IDs

IDs are generated by the Fluent platform and are guaranteed to be unique at the time of creation. The system enforces this uniqueness to ensure that each entity can be distinctly identified without any ambiguity. Users can not set this value via API. 

Refs 

Typically refs are values passed in via third-party integrations and should represent the IDs from external systems. On occasion when internal rules and workflows generate refs they are guaranteed to be unique e.g. Fulfilments.

• Order/fulfilment/article (Refs): The system does not enforce the uniqueness of refs across retailers for these entities at the time of creation and only enforces uniqueness at the retailer level. However, queries such as getOrderByRef will fail if they are not unique across retailers. 
• Product/Inventory/Virtual Catalogues (Refs): Within the context of product, inventory, or virtual catalogues, refs are unique only within the specific catalogue. This means that the same ref can exist in multiple catalogues, allowing the same position to be used in various virtual catalogues, for example.
• Uniqueness Assumption: Many rules and workflows within the system assume that refs are unique. Maintaining this uniqueness is important to ensure the proper functioning of these rules and workflows.

Why Refs?

Fluent is typically integrated with many other services, so orders will come from one service, products from another, and inventory from a third.

While Fluent generates unique identifiers for each of these, tracking those across many services would mean updating each one (e.g., adding a table column to store the Fluent ID, updating the REST endpoint to return it, etc.).

However, those services will usually already have a unique identifier for the order/product/inventory position. To simplify things, Fluent provides a second unique identifier for each entity in the ref field.

Rather than being auto-generated, the ref can be set by the service or connector creating the entity. This means that integrations can use the existing ID from the external service to retrieve and update the entity without making changes on the other end.

Recommended Practices

• Unique Refs: Despite the system not enforcing the uniqueness of refs, it is highly recommended to have unique refs for all entities. Changing the data model structure to fetch refs specific to a retailer is not an option. 
• Unique Refs in Catalogues: While refs can be duplicated across different catalogues, strive to maintain their uniqueness within each specific catalogue to facilitate easier tracking and management.
• Child Entities: Use the unique identifier of the parent entity when creating refs for child entities. This can be done by incorporating the parent entity's ID into the ref, such as using "<order_id>-some-ref-value" for fulfillments created from an order. 
• Fields: The username field for user and customer entities should follow the same practices of being unique to the nearest container.
• Consistency: Adopting a consistent approach to handling refs and IDs can greatly simplify entity management and reduce the risk of errors.