API Extensions

This track will teach you how to extend the FastStore API schema by adding new data to the existing queries.

While the FastStore API provides a GraphQL schema that caters to common use cases, some stores may require access to additional and more specific data. If you need to retrieve data not natively provided by the FastStore API, you can achieve this by extending the FastStore API schema and incorporating new data into the existing queries.

Please be aware that introducing additional API endpoints to your storefront can potentially affect site performance, as already covered in Best practices for fetching data.

Main concepts

GraphQL Optimizations & types

GraphQL optimizations are seamlessly executed, requiring no direct intervention from end developers. They are essential for optimizing your GraphQL server and TypeScript types and provide benefits such as:

Build-time generated mappings of declared queries.
Improved efficiency and security.
Enforcement of predefined operations.

They are automatically triggered every time you start a development server (yarn dev) or build the store (yarn build). Resolver changes are automatically and instantly visible without the need for manual optimization generation. Without these optimizations, any changes to the GraphQL schema, such as adding or removing fields from a query or changing a GraphQL type, won't be reflected in the store.

Extendable queries

Extendable queries in FastStore's GraphQL API are predefined GraphQL queries that serve as a foundation for retrieving data from the API. These queries allow you to add or change fields within the query to tailor the data retrieval process to the store-specific needs.

Fetching only the data you need

GraphQL allows you to customize your query to get precisely the data you need, which reduces the data returned from the requests. Double-check your queries to make sure they are not over-fetching.

This also means that you must be mindful of the data added to your query with GraphQL fragments returned. Use them only when they do not include unnecessary data.

Do not send direct requests to external APIs

Do not make direct requests to external APIs to avoid compromising website performance and 504 timeout errors. Instead, use the FastStore API extension to access other data not available in the native FastStore API schema.

If you need data that is not available on the native FastStore GraphQL schema, check the root object. The GraphQL root object represents the top-level object returned to a query. You can see the data that is available in the root object by adding logs.

Avoid custom API Routes

We do not recommend using Next.js API Routes other than the ones already built-in in FastStore.

If you do use this type of function, you must always check which ones are actually running and remove the ones that are not.

Extending VTEX API schemas

Extend VTEX and third-party APIs to customize how data is managed and processed in your store.

Extending queries using fragments

Extend GraphQL queries using fragments in FastStore API Extension to add custom fields to predefined queries.