Documentation
Feedback
Guides
Storefront Development

Storefront Development
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 and resolvers 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:

_10
mkdir graphql

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

_10
mkdir vtex

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

_10
mkdir resolvers typeDefs

The src/graphql/vtex/resolvers and src/graphql/vtex/typeDefs paths are mandatory when adding VTEX API Extensions, but you can organize the files inside those directories as you wish.
  1. 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:

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

Note that in the code example above, the type definitions and resolvers files were created at <resolverName>.ts and <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 type from FastStore API, so the name of the file is product.graphql.> ℹ️ The way that it will be organized inside this folder is flexible, it's possible to create multiple typeDefs files or group them all together in just one file. During the build process and when running the local server file, all .graphql files under this directory will be considered.
  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.
"graphql/vtex/typeDefs/product.graphql"

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

The typeDefs files must have .graphql extension. Also, the index.ts is not needed for typeDefs, only for resolvers.
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 type example, so the name of the file is product.ts.
The way that it will be organized inside this folder is flexible, it's possible to create multiple resolvers files or group them all together in just one file.
  1. 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.
copy

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

Note that you can leverage the use of TypeScript by typing the root param as StoreProductRoot:
{"base64":"  ","img":{"width":1908,"height":655,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":406244,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/root-field-ts___3a10ec8a1aeba9770c7ee982995d55bc.gif"}}
  1. Open the index.ts file inside the vtex/resolvers folder and import the resolver, StoreProductResolver, you created in the previous step.
  2. Export a new resolvers object that includes the imported resolver(s).
copy

_10
import { default as StoreProductResolver } from './product'
_10
_10
const resolvers = {
_10
...StoreProductResolver,
_10
}
_10
_10
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.
If the changes you made are still not available, refer to the troubleshooting section GraphQL changes not visible during development.

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

For third-party API schemas, you only need to add the thirdParty folder within the 'src/graphql' directory.
  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:

_10
mkdir graphql

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

_10
mkdir thirdParty

  1. In thirdParty, create resolvers and typeDefs subfolders.

_10
mkdir resolvers typeDefs

The src/graphql/vtex/resolvers and src/graphql/vtex/typeDefs path is mandatory, but you can organize the files inside those directory as you wish.
  1. 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:

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

This directory structure distinguishes between data originating from VTEX and data from third-party APIs.

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 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:
copy

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

  1. 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.
copy

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

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

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

  1. 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:
copy

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

Once you have defined these files in the thirdParty folder, you can query the data you defined.
If the changes you made are still not available, refer to the troubleshooting section GraphQL changes not visible during development.
Contributors
1
Photo of the contributor
+ 1 contributors
Was this helpful?
Yes
No
Suggest edits (Github)
Contributors
1
Photo of the contributor
+ 1 contributors
On this page