search
API documentationIncident ManagementFeedback
githubEdit

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.

circle-exclamation

The specific entities that support the URN pattern are detailed in the REST API Referencearrow-up-right.

hashtag
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 8141arrow-up-right.

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

Last updated