Extending API schemas

In this guide, learn how to extend VTEX and third-party APIs to customize them according to your store's needs, allowing you to efficiently retrieve and manipulate the necessary data.

Before you start

Avoid over-fetching data on pages

Even though you can add information to the FastStore API schema, you must be careful not to over-fetch data on your pages. See the best practices for fetching data on your storefront.

Extending VTEX API Schemas

FastStore streamlines the way of using data from VTEX APIs that the FastStore API does not expose.

As FastStore uses GraphQL, it's required to write type definitions (opens in a new tab) and resolvers (opens in a new tab) to fetch the data you need. To define new type definitions and resolvers for FastStore using GraphQL, learn how to create a specific directory structure in the following step by step.

Step by step

Step 1 - Preparing the folders and files

To declare a new type definition and resolver, create the following directory structure:

1. In your store repository, go to the src folder and create the graphql subfolder. You can do this by running the following command in your terminal:

mkdir graphql

2. Inside the new graphql folder, create the vtex subfolder.

mkdir vtex

3. In the vtex folder, create resolvers and typeDefs subfolders.

mkdir resolvers typeDefs

4. Create a index.ts file inside the resolvers folder.

Once you have created the essentials folders, you will have a folder structure for the VTEX API Schema extensions in the src/graphql/vtex folder similiar to the the following:

starter.store/
└─ src/
    └─ graphql/
        └─ vtex/
          ├─ resolvers/
              └─ index.ts
              └─ <resolverName>.ts
              └─ …
          ├─ typeDefs/
              └─<typeName>.graphql
              └─ …

Step 2 - Creating type definitions (typeDefs)

Your new type definitions set the data structure for your new fields, extended from the existing FastStore API GraphQL queries and types.

1. Create a new <typeName>.graphql file inside the vtex/typeDefs folder. For example, let's extends the StoreProduct (opens in a new tab) type from FastStore API, so the name of the file is product.graphql.

2. To extend the StoreProduct, let's add a customData field in the product.graphql and it should return a string value. This field can store custom information related to a product in your store. For example, you might use this field to store additional product details that are not present in the native FastStore API schema.

 
extend type StoreProduct {
  """
  Custom data extending StoreProduct
  """
  customData: String!
}
 

Now, refer to the next step to create the resolvers to provide the actual data to the customData field.

Step 3 - Creating resolvers

Now, let's create a resolver to define how the new customData field should be resolved, or in other words, what data or logic should be associated with them when queried.

1. Create a new <resolverName>.ts file inside the vtex/resolvers folder. Let's continue the StoreProduct (opens in a new tab) type example, so the name of the file is product.ts.

2. Define the resolver in the product.ts file. This resolver specifies how to fetch the data for the customData field based on the root object.

import type { StoreProductRoot } from '@faststore/core/api'
 
const productResolver = {
  StoreProduct: {
    customData: (root: StoreProductRoot) => {
      return 'My item id: ' + root.itemId
    },
  },
}
 
export default productResolver

Note that you can leverage the use of TypeScript by typing the root param as StoreProductRoot (opens in a new tab):

3. Open the index.ts file inside the vtex/resolvers folder and import the resolver, StoreProductResolver, you created in the previous step.

4. Export a new resolvers object that includes the imported resolver(s).

import { default as StoreProductResolver } from './product'
 
const resolvers = {
  ...StoreProductResolver,
}
 
export default resolvers

Once you have defined these files in the vtex folder, the new fields are already available for use. To consume the fields, refer to the Consuming FastStore API extension with custom components guide.

Extending FastStore API with third-party API schemas

As stores tend to grow, so does the possibility of consuming new data that is not provided by default in the FastStore API or other VTEX APIs. As such, FastStore must consume new data from third-party APIs.

Step by step

Step 1 - Preparing the folders and files

1. In your store repository, go to the src folder and create the graphql subfolder. You can do this by running the following command in your terminal:

mkdir graphql

2. Inside the new graphql folder, create the thirdParty subfolder.

mkdir thirdParty

3. In thirdParty, create resolvers and typeDefs subfolders.

mkdir resolvers typeDefs

4. Create a index.ts file inside the resolvers folder.

Once you have created the essentials folders, you will have a folder structure similiar to the the following:

starter.store/
└── src/
    └── graphql/
        ├── thirdParty/
        │   ├── resolvers/
        │       └── index.ts
        │       └── <resolverName>.ts
        │       └── …
        │   ├── typeDefs/
        │       └── <typeName>.graphql
        │       └── …

Step 2 - Creating type definitions and resolvers

1. Create a new <typeName>.graphql inside the thirdParty folder. As we are creating new queries, the name of the file that defines the type definitions can be extra.graphql.
2. Create a new <resolver>.ts file inside the graphql/thirdParty/resolvers folder.

Step 3 - Creating query or mutation schemas

It's important to mention that it's possible to extend the existing FastStore API Objects (opens in a new tab) as mentioned in the Extending VTEX API Schemas, or even create new queries entry points. Below, you'll find an example of code for implementing a third-party extension using new queries.

1. In the extra.graphql file, add the following:

 
type ExtraData {
  """
  Data customizing ExtraData
  """
  data: String!
}
 
type Query {
  extraData: ExtraData
  namedExtraData(name: String!): ExtraData
}

2. In the <resolver>.ts file, let's continue the example, so the file name can be extra.ts. This file defines the resolvers that handle the logic for the defined queries or mutations.

 
const extraDataResolver = {
  Query: {
    extraData: () => {
      return {
        data: 'Extra data',
      }
    },
    namedExtraData: (_, { name }) => {
      return {
        data: `Named extra data: ${name}`,
      }
    },
  },
}
 
export default extraDataResolver

3 - In the graphql/thirdParty/resolvers folder, create an index.ts file to combine all the resolvers into a single object.

 
import { default as StoreExtraResolver } from './extra'
 
const resolvers = {
  ...StoreExtraResolver,
}
 
export default resolvers

4 - With the schema and resolvers in place, you can query the data using GraphQL queries. Here's an example query to access the extra data:

query {
	extraData {
		data
	}
	namedExtraData(name: "Hello") {
		data
	}
}

Once you have defined these files in the thirdParty folder, you can query the data you defined.