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.