# API reference This section of the documentation describes all of the fulfillmenttools APIs that are available to use. Use the left-hand navigation to find the relevant endpoint, or use the search bar. You can also find the [models](https://docs.fulfillmenttools.com/documentation/apis/api-reference/models "mention") for all APIs. We recommend reading the [API versioning and lifecycle article](https://docs.fulfillmenttools.com/documentation/apis/api-versioning-and-lifecycle), as well as the [Accessing to fulfillmenttools APIs article](https://docs.fulfillmenttools.com/documentation/getting-started/access-to-fulfillmenttools-apis) 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.
### Pagination fulfillmenttools offers a pagination interface for most endpoints. Pagination relies on the `size` and `startAfterId` query parameters. ```http 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. {% hint style="warning" %} The maximum value for the `size` parameter for a single `REST API` call is `500`. {% endhint %} ### 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: ```json { "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: ```http 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: ```http 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](https://datatracker.ietf.org/doc/html/rfc8141). * `NO-5678-22`: This is the value of the `tenantFacilityId` for the specific facility. `fulfillmenttools` ensures this value is unique. ## GraphQL API {% hint style="success" %} The GraphQL API is in a beta stage. Refer to the [Limitations section](#limitations) for further information. {% endhint %} The fulfillmenttools GraphQL API is reachable at `https://{YOUR-TENANT-NAME}.graphql.fulfillmenttools.com/graphql`. The API can be explored using the [GraphQL Explorer](https://docs.fulfillmenttools.com/documentation/getting-started/access-to-fulfillmenttools-apis#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](https://graphql.org/learn/queries/#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 & lifecycle](https://docs.fulfillmenttools.com/documentation/apis/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.