GraphQL API

Our GraphQL API is currently in a beta stage. Please check the Limitations section for further information.

Our GraphQL API is reachable under https://{YOUR_TENANT}.graphql.fulfillmenttools.com/graphql. Just Curious? Try it out in our 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

In order to help with your support requests and to improve our service, we ask you to provide a client identification token when making calls from your production apps to our GraphQL API. This helps us distinguish between manual queries ( for example via the fulfillmenttools GraphQL Explorer) and your app deployments.

Please provide the client identification token in the following header:

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

A sample input to this header could be fft-picking-app/0.22.

If you do not provide a client ID header, you can still use the API as usual. We reserve the right to change the format of client ID header or make client identification mandatory at any time during the beta phase and will notify you if action on your side is necessary.

Best practices

When integrating with our GraphQL API, consider the following best practices to ensure optimal performance and reliability:

• Fetch Only Necessary Data: Specify the exact fields you need in your 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: Do not inline your data into the GraphQL Document. Use Variables instead.

• Handle Errors Gracefully: With semantic nullability, you can easily handle partial results to increase application resilience.

• Paginate Large Lists: Use 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 our API documentation for updates or changes, especially during the beta phase.

Limitations

The GraphQL API is currently in a beta stage. This means that the API is not yet stable and internal fields or alpha features might change without notice. We are working hard to improve the API and make it generally available as soon as possible. For production use, we recommend restricting api usage to fields and types marked at least as BETA. For further information, please check our API Versioning & lifecycle guide.

Query Complexity & Rate Limiting

At the moment, we do not enforce any query complexity or cost limits on the GraphQL API. This will change with the transition to general availability. In the future, we plan to implement query complexity analysis to ensure fair usage.

What You Should Do:

• Optimize Queries: Begin optimizing your queries now to request only the data you need.

• Avoid Excessive Nesting: Limit the depth of nested queries to reduce complexity.

• Prepare for Limits: Be aware that queries exceeding complexity thresholds may be rejected in the future. We will notify you in advance of any changes.

Even with these limits in sight, don't hesitate to group data for the same view in a single query.