Documentation
Feedback
Guides
VTEX IO Apps

VTEX IO Apps
Rewriter GraphQL API
vtex.rewriter
Version: 1.63.0
Latest version: 1.63.3

This page is about version 1.63.0 of the app, which is not the most recent version. The latest stable version is 1.63.3.

This article serves as a comprehensive guide to the GraphQL API provided by the Rewriter app. This API allows managing internal URLs and URL redirects.

Routes stored in the Rewriter commonly have complex paths, since they communicate with other systems and databases. To improve client-side usage and SEO rankings, the Rewriter app has, in the definition of the routes, the standard paths along with canonical (shorter) paths. For instance, the standard path to a product is /_v/segment/routing/vtex.store@2.x/product/:id/:slug/p, while the canonical path to a product is /:slug/p.

The Rewriter app is responsible for three main types of routes: product, search, and navigation routes.

The first two are first-class entities in Rewriter, meaning Rewriter identifies these routes and directly forwards them to the rendering pipeline.

Navigation routes, in turn, are client-side defined routes related to custom paths and VTEX IO pre-defined templates, such as department, brand, and category routes. These routes can have a canonical path and a search query string.

In Rewriter, navigation routes are identified by the internal type, and routes used to redirect a route from one path to another are identified by the redirect type.

The table below summarizes the classification of routes used in the API.

Type of routeDescription
InternalIdentifies navigation routes. Its standard path can have segments specifying the communication with other systems such as databases or apps, possibly making them long. It can be associated with a canonical path, omitting some segments, for improved client-side usage and SEO ranking.
RedirectNavigation route that redirects one path to another. There are various reasons to use a redirect including URL changes, content removal, SEO and navigation improvements, and others.

Rewriter includes functionalities to:

  • Create an internal route.
  • Create a canonical path related to an internal route.
  • Create a redirect route.
  • Delete an internal route.
  • Delete a canonical path related to an internal route.
  • Delete a redirect route.
  • Create translated URLs for cross-border stores.

In the following sections are the definitions of endpoints and parameter descriptions of the Rewriter GraphQL API.

Schema overview

Query

Query version: String redirect: QueryRedirect! internal: QueryInternal! QueryRedirect get(path:String!, locator:RouteLocator): Redirect listRedirects(limit:Int, next:String): ListRedirectsResponse! Query: redirect QueryInternal get(path:String!, locator:RouteLocator): Internal listInternals(limit:Int, next:String): ListInternalsResponse! routes(locator:EntityLocator): [RoutesByBinding!] Query: internal Redirect from: String! to: String! endDate: String type: RedirectTypes! binding: String! origin: String QueryRedirect: get ListRedirectsResponse routes: [Redirect!] next: String QueryRedirect: listRedirects Internal from: String! declarer: String! type: String! id: String! query: JSON binding: String! endDate: String imagePath: String imageTitle: String routesVersion: Float resolveAs: String origin: String disableSitemapEntry: Boolean QueryInternal: get ListInternalsResponse routes: [Internal!] next: String QueryInternal: listInternals RoutesByBinding binding: String! route: String! QueryInternal: routes ListRedirectsResponse: routes ListInternalsResponse: routes
FieldTypeDescription
redirectQueryRedirect!Provides redirect routes data.
Redirect routes are used to redirect a route from one path to another.
internalQueryInternal!Provides internal routes data.
Internal routes are navigation routes.

Mutation

Mutation Mutation redirect MutateRedirect! internal: MutateInternal! MutateRedirect MutateRedirect save(route: RedirectInput!): Redirect saveMany(routes: [RedirectInput!]!): Boolean! delete(path: String! locator: RouteLocator): Redirect deleteMany(paths: [String!]! locators: [RouteLocator!]): Boolean! Mutation:redirectport->MutateRedirect Mutation: redirect MutateInternal MutateInternal save(route: InternalInput!): Internal saveMany(routes: [InternalInput!]!): Boolean! delete(path: String! locator: RouteLocator): Internal deleteMany(paths: [String!]! locators: [RouteLocator!]): Boolean! Mutation:internalport->MutateInternal Mutation: internal Redirect from: String! to: String! endDate: String type: RedirectTypes! binding: String! origin: String MutateRedirect:deleteport-Redirect MutateRedirect: delete Internal from: String! declarer: String! type: String! id: String! query: JSON binding: String! endDate: String imagePath: String imageTitle: String routesVersion: Float resolveAs: String origin: String disableSitemapEntry: Boolean MutateInternal:saveport-Internal MutateInternal: save MutateInternal:deleteport-Internal MutateInternal: delete MutateRedirect:saveport-Redirect MutateRedirect: save
FieldTypeDescription
redirectMutateRedirect!Updates or deletes redirect routes data according to the provided arguments.
Redirect routes are used to redirect a route from one path to another.
internalMutateInternal!Updates or deletes internal routes data according to the provided arguments.
Internal routes are navigation routes.

Schema description

Arguments must be provided by the user. The exclamation mark ! indicates that a type cannot be nullable.

QueryRedirect

Field(argument)TypeDescription
getRedirectReturns information regarding a specific redirect route, given its related path and locator.
pathString!The path of the desired route to fetch data.
locatorRouteLocatorThe RouteLocator object, containing information about the store locale and route origin.
listRedirectsListRedirectsResponse!Lists all redirect routes.
limitIntThe number of ListRedirectsResponse objects to be displayed at once.
nextStringThe argument used to fetch more internal routes from ListRedirectsResponse.
It must be empty in the first query and, in the following, filled in with the string previously obtained from the ListRedirectsResponse object.
Query 🔼

QueryInternal

Field(argument)TypeDescription
getInternalReturns information regarding a specific internal route, given its related path and locator
pathString!The path of the desired route to fetch data.
locatorRouteLocatorThe RouteLocator object, containing information about the store locale and route origin.
listInternalsListInternalsResponse!Lists all internal routes.
limitIntThe number of ListInternalsResponse objects to be displayed at once.
nextStringThe argument used to fetch more internal routes from ListInternalsResponse.
It must be empty in the first query and, in the following, filled in with the string previously obtained from the ListInternalsResponse object.
routes[RoutesByBinding!]Lists all internal routes of a specific type (e.g. deparment routes, category routes, etc.) and its related binding, which is an identifier for each store locale.
locatorEntityLocatorThe EntityLocator object, containing information about the entity type of the routes to be listed.
Query 🔼

MutateRedirect

Field(argument)TypeDescription
saveRedirectCreates or updates a redirect route according to the provided arguments.
routeRedirectInput!The data regarding the redirect route to be created or updated.
saveManyBoolean!Creates or updates many redirect routes according to the provided arguments.
routes[RedirectInput!]!The data regarding the redirect routes to be created or updated.
deleteRedirectDeletes a redirect route according to the provided arguments.
pathString!The path of the route to be deleted.
locatorRouteLocatorThe EntityLocator object, containing information about the entity type of the route to be deleted.
deleteManyBoolean!Deletes many redirect route according to the provided arguments.
paths[String!]!The paths of the routes to be deleted.
locators[RouteLocator!]The EntityLocator objects, containing information about the entity type of the routes to be deleted.
Mutation 🔼

MutateInternal

Field(argument)TypeDescription
saveInternalCreates or updates an internal route according to the provided arguments.
routeInternalInput!The data regarding the internal route to be created or updated.
saveManyBoolean!Creates or updates many internal routes according to the provided arguments.
routes[InternalInput!]!The data regarding the internal routes to be created or updated.
deleteInternalDeletes an internal route according to the provided arguments.
pathString!The path of the route to be deleted.
locatorRouteLocatorThe EntityLocator object, containing information about the entity type of the route to be deleted.
deleteManyBoolean!Deletes many internal routes according to the provided arguments.
paths[String!]!The paths of the routes to be deleted.
locators[RouteLocator!]The EntityLocator objects, containing information about the entity type of the routes to be deleted.
Mutation 🔼

Internal

FieldTypeDescription
fromString!The route path.
declarerString!The app that originally defined the route in a routes.json file.
For VTEX IO pre-defined routes, the declarer value is vtex.store@2.x.
typeString!The route entity type defined in the declarer app, which can be: department, category, subcategory, brand, etc.
idString!The entity type id. For example, a deparment id.
queryJSONThe query string parameters of a route.
bindingString!The id of the binding which the route is available.
Keep in mind: Every store has a binding id related to its store locale. Hence, cross-border stores always have more than one binding, while accounts with a single storefront have only one binding id.
endDateStringThe date a route stops being valid.
Keep in mind: The endDate value for permanent routes is null.
imagePathString
imageTitleString
routesVersionFloatThe current routes version.
Keep in mind: If the routesVersion value is null or different from the current version, the route is not currently available in the store.
resolveAsStringAlias paths of a route, meaning that the route will resolve the paths defined in the resolveAs field
Keep in mind: The resolveAs parameter must always be defined in the catalog's default language.
originStringA string that defines the origin of the route, for example: user-canonical
disableSitemapEntryBooleanThe boolean value that indicates if a route is included (False) or not (True) in the store's sitemap.
QueryInternal 🔼
MutateInternal 🔼

ListInternalsResponse

FieldTypeDescription
routes[Internal!]Returns the demanded information from the Internal object for each route.
nextStringReturns a string to be used as the next argument of the succeeding listInternals query to fetch more data.
When next returns null, all data have already been fetched.
QueryInternal 🔼

RoutesByBinding

FieldTypeDescription
bindingString!The id of the binding which the route is available.
Keep in mind: Every store has a binding id related to its store locale. Hence, cross-border stores always have more than one binding, while accounts with a single storefront have only one binding id.
routeString!Returns the route path.
QueryInternal 🔼

Redirect

FieldTypeDescription
fromString!The original route path.
toString!The route redirect path.
endDateStringThe date a redirect route stops being valid.
Keep in mind: The endDate value for permanent routes is null.
typeRedirectTypes!The route type: temporary or permanent.
bindingString!The id of the binding which the route is available.
Keep in mind: Every store has a binding id related to its store locale. Hence, cross-border stores always have more than one binding, while accounts with a single storefront have only one binding id.
originStringA string that defines the origin of the route, for example: user-canonical
QueryRedirect 🔼
MutateRedirect 🔼

ListRedirectsResponse

FieldTypeDescription
routes[Redirect!]Returns the demanded information from the Redirect object for each route.
nextStringReturns a string to be used as the next argument of the succeeding listInternals query to fetch more data.
When next returns null, all data have already been fetched.
QueryRedirect 🔼

EntityLocator

FieldTypeDescription
idString!The entity type id. For example, a deparment id.
typeString!The route entity type, which can be: department, category, subcategory, brand , etc
QueryInternal 🔼

InternalInput

FieldTypeDescription
fromString!The route path.
declarerString!The app that originally defined the route in a routes.json file.
For VTEX IO pre-defined routes, the declarer value is vtex.store@2.x.
typeString!The route entity type, which can be: department, category, subcategory, brand , etc
idString!The entity type id. For example, a deparment id.
queryJSONThe query string parameters of a route.
bindingStringThe id of the binding which the route is available.
Keep in mind: Every store has a binding id related to its store locale. Hence, cross-border stores always have more than one binding, while accounts with a single storefront have only one binding id.
endDateStringThe date a route stops being valid.
Keep in mind: The endDate value for permanent routes is null.
imagePathString
imageTitleString
resolveAsStringAlias paths of a route, meaning that the route will resolve the paths defined in the resolveAs field.
Keep in mind: The resolveAs parameter must always be defined in the catalog's default language.
originStringA string that defines the origin of the route, for example: user-canonical
disableSitemapEntryBooleanThe boolean value that indicates if a route is included (False) or not (True) in the store's sitemap.
MutateInternal 🔼

RedirectInput

FieldTypeDescription
fromString!The original route path.
toString!The route redirect path.
endDateStringThe date a route stops being valid.
Keep in mind: The endDate value for permanent routes is null.
typeRedirectTypes!The route type: temporary or permanent.
bindingStringThe id of the binding which the route is available.
Keep in mind: Every store has a binding id related to its store locale. Hence, cross-border stores always have more than one binding, while accounts with a single storefront have only one binding id.
originStringA string that defines the origin of the route, for example: user-canonical
MutateRedirect 🔼

RouteLocator

FieldTypeDescription
fromString!The original route path.
bindingString!The id of the binding which the route is available.
Keep in mind: Every store has a binding id related to its store locale. Hence, cross-border stores always have more than one binding, while accounts with a single storefront have only one binding id.
QueryRedirect 🔼
QueryInternal 🔼
MutateRedirect 🔼
MutateInternal 🔼

RedirectTypes

Value
PERMANENT
TEMPORARY
Redirect 🔼
RedirectInput 🔼
See also
Vtex.rewriter
VTEX IO Apps
VTEX App Store
VTEX IO Apps