Example REST API

Planning to develop an API for your eCommerce platform to support React Storefront? Here's an example API contract to give you a sense of what data a PWA needs. All methods below return data in JSON format.

General Guidelines

Keep user-specific data separate

In order to provide the best performance, it's important to maximize the cacheability of URLs in the PWA. Any data that is user-specific, such as localized pricing, custom product recommendations, order history, etc... should be kept separate from API endpoints that provide data for the main product catalog and shopping flow.

React Storefront will make separate API calls to get user-specific information once the page has rendered. This ensures TTFP is minimized and the application reacts quickly to user input.

For example, product data that is the same for all users could be provided by a route /products/:id, while user-specific recommendations for cross-sold products should be provided by separate route like /products/:id/recommendations.

In this scenario /products/:id would be cacheable and thus usable during the initial server-side rendering of product pages, while /products/:id/recommendations would be called to lazily add recommendations below the fold after the product page has loaded.

Keep Responses Small

Response size can greatly affect the time it takes to display data to the user. Include only what is needed in each API response. Don't include extra data because it might one day be used.

Menu

GET /menu

Retrieves the items for the main menu. This can either be a separate method or mixed into the result of other methods since the data returned here will be displayed on every page.

Returns

{
  menu: [{          // an array of menu items
    text: string,   // the text for the menu item
    url: string,    // the URL to link to
    items: [...],   // an array of nested items following the same structure
  }],
  tabs: [{          // optional, navigation tabs to display at the top of the site
    text: string,   // the text for the tab
    url: string,    // the URL to link to
    items: [...],   // an array of nested items following the same structure
  }]
}

Homepage

GET /home

Gets the content to display on the homepage. Generally, homepage content is delivered in the form of HTML blobs which are stored in the underlying platform's CMS. This may contain other structured content as needed.

Returns

{
  slots: {          // An object whose keys are slot names and values are HTML blobs from the CMS
    slot1: string,  // HTML content for CMS slot 1
    slot2: string,  // HTML content for CMS slot 2
    ...
  }
}

Category

GET /categories/:id

Gets the data to display a category page, including a list of subcategories.

Parameters

  • id: string - The of the category

Returns

{
  id: string,           // the id of the category
  name: string,         // the name of the category
  description: string,  // descriptive/SEO text to display
  subcategories: [{     // an array of subcategories to link to
    id: string,         // the id of the subcategory,
    image: string,      // an image for the subcategory
    url: string         // the URL for the subcategory
  }],
  slots: {              // An object whose keys are slot names and values are HTML blobs from the CMS
    slot1: string,      // HTML content for CMS slot 1
    slot2: string,      // HTML content for CMS slot 2
    ...
  }
}

Subcategory

GET /subcategories/:id?filter=(string)&sort=(string)&page=(integer)

Gets the data to display a subcategory page, including a list of products. Supports sorting, filtering, and paging.

Parameters

  • id: string - The of the subcategory
  • filter: string[] - One or more facets to filter by
  • sort: string - A facet to sort by
  • page: integer - The page of records to display

Returns

{
  id: string,           // the id of the category
  name: string,         // the name of the category
  description: string,  // descriptive/SEO text to display
  items: [{             // an array of products to link to
    id: string,         // the id of the product
    image: string,      // a thumbnail image for the product
    url: string,        // the URL for the product
    price: string,      // the price of the product, might contain text as well, like "from $19.99"
    oldPrice: string,   // A price to cross out if the item is on sale
    rating: integer     // the product rating (number of stars), if available
  }],
  facetGroups: {        // an array of facet groups for filtering
    name: string,       // the name of the facet group to display
    facets: [{          // an array of facets in the group
      name: string,     // the name of the facet to display
      code: string,     // the code to send as the `filter` parameter when filtering
    }]
  },
  sortOptions: [{       // an array of facets that the user can sort by
    name: string,       // the name of the facet to display
    code: string        // the code to send as the `sort parameter`
  }],
  slots: {              // An object whose keys are slot names and values are HTML blobs from the CMS
    slot1: string,      // HTML content for CMS slot 1
    slot2: string,      // HTML content for CMS slot 2
    ...
  }
}

GET /search/:text?filter=(string)&sort=(string)&page=(integer)

Retreives a set of products matching text entered by the user. Supports sorting, filtering, and paging.

Parameters

  • text: string - The search text entered by the user
  • filter: string[] - One or more facets to filter by
  • sort: string - A facet to sort by
  • page: integer - The page of records to display

Returns

{
  items: [{             // an array of products to link to
    id: string,         // the id of the product
    thumbnail: string,  // a thumbnail image for the product
    url: string,        // the URL for the product
    price: string,      // the price of the product, might contain text as well, like "from $19.99"
    rating: integer     // the product rating (number of stars), if available
  }],
  facetGroups: {        // an array of facet groups for filtering
    name: string,       // the name of the facet group to display
    facets: [{          // an array of facets in the group
      name: string,     // the name of the facet to display
      code: string,     // the code to send as the `filter` parameter when filtering
      matches: integer  // the number of items having the value
    }]
  },
  sortOptions: [{       // an array of facets that the user can sort by
    name: string,       // the name of the facet to display
    code: string        // the code to send as the `sort parameter`
  }],
  slots: {              // An object whose keys are slot names and values are HTML blobs from the CMS
    slot1: string,      // HTML content for CMS slot 1
    slot2: string,      // HTML content for CMS slot 2
    ...
  }
}

Product

GET /products/:id

Gets a product by id. This is likely the method that will differ the most from project to project, according to the unique aspects of the type of product being sold. Here are some of the most common types of product data:

Parameters

  • id: string - The id of the product

Returns

{
  id: string,           // the id of the product
  name: string,         // the name of the product,
  description: string,  // descriptive/seo text to display
  images: string[],     // a list of images to display
  thumbnails: string[], // a list of thumbnails corresponding to each image - generally displayed below the image swiper
  price: string,        // the price of the product, might contain text as well, like "from $19.99"
  oldPrice: string,     // A price to cross out if the item is on sale
  rating: integer       // the product rating (number of stars), if available
  options: {            // A set of options that the user can choose from to customize the product.  These can differ from product to product and brand to brand.
    sizes: [{           // for example, sizes
      name: string,     // the user-facing name of the option
      code: string      // an option code
    }],    
    colors: [{          // some options, such as color, might come with a thumbnail or swatch.
      name: string,
      image: string
    }],
    ...
  },
  slots: {              // An object whose keys are slot names and values are HTML blobs from the CMS
    slot1: string,      // HTML content for CMS slot 1
    slot2: string,      // HTML content for CMS slot 2
    ...
  }
}

Cart

GET /cart

Gets the contents of the user's shopping cart. Cart data is generally retrieved using a session cookie send with the request.

Returns

{
  items: [{             // an array of products in the user's cart
    id: string,         // the id of the product
    name: string,       // the name of the product
    thumbnail: string,  // a thumbnail image to display
    price: string,      // the current price
    oldPrice: string,   // an old price to cross out if the item is on sale
    rating: integer,    // the product rating
    quantity: integer,  // the quantity 
    options: {          // various selectable product options, these may differ greatly by product an brand.  Here are some examples:
      color: {
        name: string,   // The user-facing name of the option,
        code: string    // The option code
      },
      size: {
        name: string,   // The user-facing name of the option,
        code: string    // The option code
      },
      ...
    },
    slots: {              // An object whose keys are slot names and values are HTML blobs from the CMS
      slot1: string,      // HTML content for CMS slot 1
      slot2: string,      // HTML content for CMS slot 2
      ...
    }
  }]
}

Replace Cart

POST /cart

Replaces the cart's contents.

Body

The request body is generally JSON of the format returned by GET /cart above.

Returns

No data is returned from this request