API reference

RESTful API

The Representational State Transfer (REST) Application Programming Interface (API) is the primary interface to fulfillmenttools. It provides endpoints to create entities such as orders, pick jobs, and shipments, and to retrieve information about existing entities.

Drawing

Pagination

fulfillmenttools offers a pagination interface for most endpoints. Pagination relies on the size and startAfterId query parameters.

GET /api/orders?size=20&startAfterId={entityId}

This call returns 20 entities starting after (not including) the entity with the specified entityId. The default value for the size query parameter is 25 on paginated queries.

The maximum value for the size parameter for a single REST API call is 500.

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

fulfillmenttools 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.

GraphQL API

The GraphQL API is in a beta stage. Refer to the Limitations section for further information.

The fulfillmenttools GraphQL API is reachable at https://{YOUR-TENANT-NAME}.graphql.fulfillmenttools.com/graphql. The API can be explored using the GraphQL Explorer.

Semantic nullability

The beta API implements the current draft of the GraphQL semantic nullability specification on connections and root-level fields.

Client identification

Providing a client identification token when making calls from production applications to the GraphQL API helps distinguish between automated queries and manual queries, such as those made via the GraphQL Explorer. This aids in support requests and service improvements.

The client identification token is provided in the following header:

X-User-Agent: {AppName}/{AppVersion}

A sample value for this header is fft-picking-app/0.22.

The API can be used without a client ID header. During the beta phase, the format of the client ID header may change, or client identification may become mandatory. Notification will be provided in advance of any required changes.

Best practices

The following best practices for integrating with the GraphQL API ensure optimal performance and reliability:

• Fetch only necessary data: Specify the exact fields needed in queries to minimize payload size and improve performance.

• Make a single request for each view: Fetch all required data in a single query to reduce latency and improve performance.

• Use query variables: Avoid inlining data into the GraphQL Document. Employ Variables instead.

• Handle errors gracefully: Utilize semantic nullability to handle partial results and increase application resilience.

• Paginate large lists: Employ pagination techniques like first, last, before, and after to manage large datasets efficiently.

• Limit query complexity: Avoid deeply nested queries or overly complex operations that can impact performance.

• Stay updated: Regularly review the API documentation for updates or changes, especially during the beta phase.

Limitations

The GraphQL API is in a beta stage. As a beta feature, the API is subject to change, and internal fields or alpha features may be modified without notice. For production environments, it is recommended to restrict API usage to fields and types marked as BETA or higher. For further information, refer to the API Versioning & lifecycle guide.

Query complexity and rate limiting

The beta version of the GraphQL API does not enforce query complexity or cost limits. These limits will be introduced as the API moves toward general availability. Future versions will include query complexity analysis to ensure fair usage.

To prepare for these future limits, queries should be optimized to request only necessary data and avoid excessive nesting, which reduces complexity. In future releases, queries that exceed complexity thresholds may be rejected. Any such changes will be announced in advance.

Grouping data for the same view into a single query remains a recommended practice.