API reference

This section of the documentation describes all the fulfillmenttools APIs available for use. Use the sidebar navigation to find the relevant endpoint, or use the search bar. You can also find the models for all APIs.

We recommend reading the API versioning and lifecycle article, as well as the Accessing to fulfillmenttools APIs article and the General concepts article first.

The rest of this article will explain working with REST or GraphQL.

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.

Base URL

https://ocff-{projectId}.api.fulfillmenttools.com

Responses

fulfillmenttools uses conventional HTTP response codes to indicate the success or failure of an API request.

In general:

• Codes in the 2xx range indicate success.

• Codes in the 4xx range indicate an error that failed given the information provided.

• Codes in the 5xx range indicate an error with fulfillmenttools' servers (these are rare).

Response code	Interpretation	Explanation
200	OK	Everything worked as expected.
201	Created	Created as expected.
400	Bad request	The request was unacceptable, often because a required parameter was missing.
401	Unauthorized	No valid API key provided.
403	Forbidden	The API key doesn't have permissions to perform the request.
404	Not found	The requested resource doesn't exist.
409	Conflict	The request conflicts with another request.
429	Too many requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 503, 504	Internal server error, service unavailable, timeout	Something went wrong on fulfillmenttools' end (these are rare).

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.

Using the URN pattern

Typically, a fulfillmenttools entity is referenced by its id, a unique identifier that's automatically generated 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's recommended to restrict API usage to fields and types marked as Beta or higher. For further information, refer to the API versioning and 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.