Retrieving Ratings and Reviews
  • 13 Aug 2020
  • 7 Minutes To Read
  • Print
  • Share
  • Dark
    Light

Retrieving Ratings and Reviews

  • Print
  • Share
  • Dark
    Light

Ratings and reviews allow customers to share their opinions and experiences about purchases. This enables customers to take meaningful decisions about purchases and increases their trust with the shop.

Glue REST API allows retrieving a list of ratings and reviews for each product, as well as its average rating. This can help frontend developers in building the product page, extending it with the ratings and reviews relevant to each product. Also, the average rating of each product, as well as the number of times it has been reviewed, will be available in all endpoints where abstract and concrete products can be included as a relationship, such as, for example, /catalog-search, /related-products, /up-selling-products, /abstract-alternative-products, etc.

Apart from that, the API allows developers to add the possibility for customers to post ratings and reviews.

In this article, you will learn how to perform the following tasks using REST APIs:

  • retrieve the average rating of any product;
  • retrieve a list of ratings and reviews for a product;
  • allow customers to review and rate products.

Installation

For detailed information on the modules that provide the API functionality and related installation instructions, see GLUE: Ratings and Reviews Feature Integration.

Retrieving Ratings and Reviews

Using the REST API, developers can retrieve ratings and reviews related to specific abstract or concrete products.

Request

Abstract Products

To retrieve all ratings and reviews for a specific abstract product, send a GET request to the following endpoint:

/abstract-products/{{product_sku}}/product-reviews

Sample request: GET http://glue.mysprykershop.com/abstract-products/035/product-reviews

where 035 is the SKU of the product you want to retrieve ratings and reviews for.

Alternatively, you can retrieve them as a relationship to the abstract product when requesting general product information. This option can be particularly useful to reduce the number of calls and save network traffic when displaying ratings and reviews alongside other product information, for example, on the product page.

To do so, send a request as follows:

/abstract-products/{{product_sku}}?include=product-reviews

Sample request: GET http://glue.mysprykershop.com/abstract-products/035?include=product-reviews

Concrete products
To fetch a list of ratings and reviews for a concrete product (i.e. its parent abstract product), send a request for the concrete product information and include the ratings and reviews as a relationship:

/concrete-products/{{product_sku}}?include=product-reviews

Sample request: GET http://glue.mysprykershop.com/concrete-products/035_17360369?include=product-reviews

where 035_17360369 is the SKU of the product you want to retrieve ratings and reviews for.

Response

The API responds with an array of items, each representing a single rating and review object.

Response Attributes
Each item in the array exposes the following attributes:

Attribute* Type Description
nickname String Specifies the customer’s nickname.
rating Integer Indicates the rating given to the product by a specific customer.
summary String Specifies the review summary.
description String Specifies the full text of a review.
  • The attributes mentioned are all attributes in the response. Type and ID are not mentioned.

Sample Response - Abstract Product Reviews

{
    "data": [
        {
            "type": "product-reviews",
            "id": "40",
            "attributes": {
                "rating": 3,
                "nickname": "Stephen Grumpy",
                "summary": "Not that awesome",
                "description": "The specs are good, but the build quality desires to be better."
            },
            "links": {
                "self": "http://glue.mysprykershop.com/product-reviews/40"
            }
        },
        {
           "type": "product-reviews",
           "id": "42",
           "attributes": {
                "rating": 5,
                "nickname": "John Doe",
                "summary": "Excellent product",
                "description": "Powerful processor, bright screen and beatiful design - what else do you need?"
        },
            "links": {
                "self": "http://glue.mysprykershop.com/product-reviews/42"
            }
        }
    ],
    "links": {
        "self": "http://glue.mysprykershop.com/abstract-products/139/product-reviews",
        "last": "http://glue.mysprykershop.com/abstract-products/139/product-reviews?page[offset]=10&page[limit]=10",
        "first": "http://glue.mysprykershop.com/abstract-products/139/product-reviews?page[offset]=0&page[limit]=10",
        "next": "http://glue.mysprykershop.com/abstract-products/139/product-reviews?page[offset]=10&page[limit]=10"
    }
}

Sample Response - Abstract Product Reviews as Relationship

{
    "data": {
        "type": "abstract-products",
        "id": "035",
        "attributes": {...},
        "links": {...},
        "relationships": {
            "product-reviews": {
                "data": [
                    {
                        "type": "product-reviews",
                        "id": "40"
                    },
                    {
                        "type": "product-reviews",
                        "id": "42"
                    }
                ]
            }
        }
    },
    "included": [
        {
            "type": "product-reviews",
            "id": "40",
            "attributes": {
                "rating": 3,
                "nickname": "Stephen Grumpy",
                "summary": "Not that awesome",
                "description": "The specs are good, but the build quality desires to be better."
            },
            "links": {
                "self": "http://glue.mysprykershop.com/product-reviews/40"
            }
        },
        {
           "type": "product-reviews",
           "id": "42",
           "attributes": {
                "rating": 5,
                "nickname": "John Doe",
                "summary": "Excellent product",
                "description": "Powerful processor, bright screen and beatiful design - what else do you need?"
        },
            "links": {
                "self": "http://glue.mysprykershop.com/product-reviews/42"
            }
        }
    ]
}

Sample Response - Concrete Product Reviews

{
    "data": {
        "type": "concrete-products",
        "id": "035_17360369",
        "attributes": {...},
        "links": {...},
        "relationships": {
            "product-reviews": {
                "data": [
                    {
                        "type": "product-reviews",
                        "id": "40"
                    },
                    {
                        "type": "product-reviews",
                        "id": "42"
                    }
                ]
            }
        }
    },
    "included": [
        {
            "type": "product-reviews",
            "id": "40",
            "attributes": {
                "rating": 3,
                "nickname": "Stephen Grumpy",
                "summary": "Not that awesome",
                "description": "The specs are good, but the build quality desires to be better."
            },
            "links": {
                "self": "http://glue.mysprykershop.com/product-reviews/40"
            }
        },
        {
           "type": "product-reviews",
           "id": "42",
           "attributes": {
                "rating": 5,
                "nickname": "John Doe",
                "summary": "Excellent product",
                "description": "Powerful processor, bright screen and beatiful design - what else do you need?"
        },
            "links": {
                "self": "http://glue.mysprykershop.com/product-reviews/42"
            }
        }
    ]
}

Pagination
You can improve the performance and reduce the amount of network traffic via pagination. Page links can be found in the links section of the response. The default option is to retrieve 10 results per page.

Pagination Parameters
The following page path parameters are used for pagination:

Parameter Description Example Explanation
offset Specifies the number of results to skip. ?page[offset]=10 Skip 10 results and display starting from the 11th one.
limit Specifies the number of results per single request (page). ?page[limit]=10 Return 10 results per page.
Combining paging parameters ?page[limit]=10&page[offset]=20 Display 10 results per page and show the 3rd page.

Possible Errors

Status Reason
400 The abstract product ID is not specified.
404 An abstract product with the specified ID was not found.

Getting Average Product Rating

The average rating for any product, abstract or concrete, is returned as a part of the request for product information:

  • abstract products
    Endpoint - /abstract-products/{{product_sku}}
    Sample request - GET http://glue.mysprykershop.com/abstract-products/035

  • concrete products
    Endpoint - /concrete-products/{{product_sku}}

Sample request - GET http://glue.mysprykershop.com/concrete-products/035_17360369

where 035 and 035_17360369 are the SKUs of the products you want to retrieve average ratings for.

Response

The endpoints return information on the requested products. The average rating is exposed in the averageRating attribute, and the number of times a product was reviewed is returned in the reviewCount attribute.

Sample Response

{
    "data": {
        "type": "abstract-products",
        "id": "035",
        "attributes": {
            "sku": "035",
            "averageRating": 4,
            "reviewCount": 2,
            "name": "Asus Zenbook US303UB",
            "description": "Classic design,stylish new color ASUS ZenBook series represents the essence of ASUS design spirit...",
            "attributes": {...},
            "superAttributesDefinition": [...],
            "superAttributes": [],
            "attributeMap": {...},
            "metaTitle": "Canon PowerShot N",
            "metaKeywords": "Canon,Entertainment Electronics",
            "metaDescription": "Classic design,stylish new color ASUS ZenBook series represents the essence of ASUS design spirit...",
            "attributeNames": {...},
            "url": "/en/asus-zenbook-us303ub-35"
        },
        "links": {...}
    }
}

Rating and Reviewing Products

To post a rating and review of a product, send a POST request to the following endpoint:

/abstract-products/{{product_sku}}/product-reviews

Request

The request should contain the rating a customer assigned to the product and their respective review. A review consists of a short summary, which is required, and a more detailed description, which is optional.

Sample request: POST http://glue.mysprykershop.com/abstract-products/139/product-reviews

where 139 is the SKU of the abstract product a customer wants to rate and/or review.

Request Attributes:

Attribute* Type Required Description
nickname String yes Specifies the customer’s nickname.
This nickname should be displayed each time the review is shown. The customer’s actual username used for authentication can therefore be hidden.
rating Integer yes Specifies the rating given to the product by the customer.
summary String yes Specifies the review summary.
description String no Specifies the full text of a review.
  • Type is not mentioned.

Sample Request

{
    "data": {
        "type": "product-reviews",
        "attributes": {
            "nickname": "John Doe",
            "rating": 5,
            "summary": "Excellent product",
            "description": "Powerful processor, bright screen, beatiful design and excellent build quality - what else do you need?"
        }
    }
}

Response

If the data is posted successfully, the endpoint responds with the specified rating and review, and also provides a unique identifier in the id attribute.

Response Attributes:
The response contains the same attributes as the request plus the unique identifier.

Attribute* Type Description
id String Specifies a unique review identifier.
nickname String Specifies the customer’s nickname.
rating Integer Specifies the rating given to the product by the customer.
summary String Specifies the review summary.
description String Specifies the full text of the review.
  • Type is not mentioned.

Sample Response

{
    "data": {
        "type": "product-reviews",
        "id": "42",
        "attributes": {
            "rating": 5,
            "nickname": "John Doe",
            "summary": "Excellent product",
            "description": "Powerful processor, bright screen, beatiful design and excellent build quality - what else do you need?"
        },
        "links": {
            "self": "http://glue.de.suite-nonsplit.local/product-reviews/42"
        }
    }
}

Possible Errors

Status Reason
401 The access token is invalid.
403 The access token is missing.
400 The abstract product ID is not specified.
404 An abstract product with the specified ID was not found.
422 One or more of the following reasons:
  • The nickname attribute is empty or not specified.
  • The rating attribute is empty or not specified.
  • The summary attribute is empty or not specified.
  • The format of the request is incorrect.
Was This Article Helpful?