Uniform-Resource-Name-Pattern (URN) in path parameters

The fulfillmenttools platform allows supplementing the platform-generated entity id with a custom, tenant-specific identifier. This can be used in REST API resource paths for addressing entities, which can simplify integration and reduce the total number of required requests.

The specific entities that support the URN pattern are detailed in the REST API Reference.

Using the URN pattern

Typically, a fulfillmenttools entity is referenced by its id, a unique identifier generated by the platform upon creation which is immutable. In addition, a tenant-specific identifier, such as tenantFacilityId, can be specified when an entity is created:

{
    "id": "54df9aa2-42ec-47a4-9d5a-29d1387be8fa",
    "tenantFacilityId": "NO-5678-22",
    ...
    "version": 1
}

The platform id can be used to retrieve the entity via the API. For example, to fetch a facility entity:

GET /api/facilities/54df9aa2-42ec-47a4-9d5a-29d1387be8fa

The URN pattern provides an alternative way to address an entity by using its tenant-specific identifier, provided this value is unique. This identifier often acts as a foreign key that corresponds to an ID in an external system.

The previous API call can be rewritten using the URN pattern as follows:

GET /api/facilities/urn:fft:facility:tenantFacilityId:NO-5678-22

The identifying value is composed of two main parts:

• urn:fft:facility:tenantFacilityId: This is the URN prefix that identifies the entity type (facility) and the field used for the lookup (tenantFacilityId). It follows the standard URN pattern, as described in RFC 8141.

• NO-5678-22: This is the value of the tenantFacilityId for the specific facility. fulfillmenttools ensures this value is unique.