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 route | Description |
---|---|
Internal | Identifies 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. |
Redirect | Navigation 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
Field | Type | Description |
---|---|---|
redirect | QueryRedirect! | Provides redirect routes data. Redirect routes are used to redirect a route from one path to another. |
internal | QueryInternal! | Provides internal routes data. Internal routes are navigation routes. |
Mutation
Field | Type | Description |
---|---|---|
redirect | MutateRedirect! | Updates or deletes redirect routes data according to the provided arguments.
Redirect routes are used to redirect a route from one path to another. |
internal | MutateInternal! | 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) | Type | Description |
---|---|---|---|
get | Redirect | Returns information regarding a specific redirect route, given its related path and locator. | |
path | String! | The path of the desired route to fetch data. | |
locator | RouteLocator | The RouteLocator object, containing information about the store locale and route origin. | |
listRedirects | ListRedirectsResponse! | Lists all redirect routes. | |
limit | Int | The number of ListRedirectsResponse objects to be displayed at once. | |
next | String | The 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. |
QueryInternal
Field | (argument) | Type | Description |
---|---|---|---|
get | Internal | Returns information regarding a specific internal route, given its related path and locator | |
path | String! | The path of the desired route to fetch data. | |
locator | RouteLocator | The RouteLocator object, containing information about the store locale and route origin. | |
listInternals | ListInternalsResponse! | Lists all internal routes. | |
limit | Int | The number of ListInternalsResponse objects to be displayed at once. | |
next | String | The 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. | |
locator | EntityLocator | The EntityLocator object, containing information about the entity type of the routes to be listed. |
MutateRedirect
Field | (argument) | Type | Description |
---|---|---|---|
save | Redirect | Creates or updates a redirect route according to the provided arguments. | |
route | RedirectInput! | The data regarding the redirect route to be created or updated. | |
saveMany | Boolean! | Creates or updates many redirect routes according to the provided arguments. | |
routes | [RedirectInput!]! | The data regarding the redirect routes to be created or updated. | |
delete | Redirect | Deletes a redirect route according to the provided arguments. | |
path | String! | The path of the route to be deleted. | |
locator | RouteLocator | The EntityLocator object, containing information about the entity type of the route to be deleted. | |
deleteMany | Boolean! | 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. |
MutateInternal
Field | (argument) | Type | Description |
---|---|---|---|
save | Internal | Creates or updates an internal route according to the provided arguments. | |
route | InternalInput! | The data regarding the internal route to be created or updated. | |
saveMany | Boolean! | Creates or updates many internal routes according to the provided arguments. | |
routes | [InternalInput!]! | The data regarding the internal routes to be created or updated. | |
delete | Internal | Deletes an internal route according to the provided arguments. | |
path | String! | The path of the route to be deleted. | |
locator | RouteLocator | The EntityLocator object, containing information about the entity type of the route to be deleted. | |
deleteMany | Boolean! | 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. |
Internal
Field | Type | Description |
---|---|---|
from | String! | The route path. |
declarer | String! | 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. |
type | String! | The route entity type defined in the declarer app, which can be: department , category , subcategory , brand , etc. |
id | String! | The entity type id. For example, a deparment id. |
query | JSON | The query string parameters of a route. |
binding | String! | 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. |
endDate | String | The date a route stops being valid. Keep in mind: The endDate value for permanent routes is null . |
imagePath | String | |
imageTitle | String | |
routesVersion | Float | The 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. |
resolveAs | String | Alias 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. |
origin | String | A string that defines the origin of the route, for example: user-canonical |
disableSitemapEntry | Boolean | The boolean value that indicates if a route is included (False ) or not (True ) in the store's sitemap. |
ListInternalsResponse
Field | Type | Description |
---|---|---|
routes | [Internal!] | Returns the demanded information from the Internal object for each route. |
next | String | Returns 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. |
RoutesByBinding
Field | Type | Description |
---|---|---|
binding | String! | 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. |
route | String! | Returns the route path. |
Redirect
Field | Type | Description |
---|---|---|
from | String! | The original route path. |
to | String! | The route redirect path. |
endDate | String | The date a redirect route stops being valid. Keep in mind: The endDate value for permanent routes is null . |
type | RedirectTypes! | The route type: temporary or permanent. |
binding | String! | 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. |
origin | String | A string that defines the origin of the route, for example: user-canonical |
ListRedirectsResponse
Field | Type | Description |
---|---|---|
routes | [Redirect!] | Returns the demanded information from the Redirect object for each route. |
next | String | Returns 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. |
EntityLocator
Field | Type | Description |
---|---|---|
id | String! | The entity type id. For example, a deparment id. |
type | String! | The route entity type, which can be: department , category , subcategory , brand , etc |
InternalInput
Field | Type | Description | |
---|---|---|---|
from | String! | The route path. | |
declarer | String! | 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. | |
type | String! | The route entity type, which can be: department , category , subcategory , brand , etc | |
id | String! | The entity type id. For example, a deparment id. | |
query | JSON | The query string parameters of a route. | |
binding | String | 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. | |
endDate | String | The date a route stops being valid. Keep in mind: The endDate value for permanent routes is null . | |
imagePath | String | ||
imageTitle | String | ||
resolveAs | String | Alias 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. | |
origin | String | A string that defines the origin of the route, for example: user-canonical | |
disableSitemapEntry | Boolean | The boolean value that indicates if a route is included (False ) or not (True ) in the store's sitemap. |
RedirectInput
Field | Type | Description | |
---|---|---|---|
from | String! | The original route path. | |
to | String! | The route redirect path. | |
endDate | String | The date a route stops being valid. Keep in mind: The endDate value for permanent routes is null . | |
type | RedirectTypes! | The route type: temporary or permanent. | |
binding | String | 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. | |
origin | String | A string that defines the origin of the route, for example: user-canonical |
RouteLocator
Field | Type | Description | |
---|---|---|---|
from | String! | The original route path. | |
binding | String! | 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. |
RedirectTypes
Value |
---|
PERMANENT |
TEMPORARY |