EXAMPLES OF PARTNER'S API USAGE

Introduction

In this document you will find some of the basic methods to use the Grocerest Partner REST API.

Summay

• Authentication
  • Login
  • Logout
• Retrieve Review of a product
• Retrieve Summarize Information of a list of products

Authentication

Login

In order to use our API you need a active user and have to know the username and the password of this user. Once you have this information you can call the route for authenticate it and receive the Bearer Token necessary for the other request.

$ curl -H "Content-Type: application/json" \
       -X POST \
       -d '{"username": "<your username>", "password":"<your password>"}'  \
       https://api.grocerest.com/v1.0/authentication

It will answer with a newer valid Bearer Token and your user's id. Here and example:

  {
    "userId": "cnwouifh7234bc",
    "bearerToken": "2359239759827592857b"
  }

If you will send an invalid username or password you will receive a 401 HTTP RESPONSE with the description of the error as payload like the following:

 {
   "error": {
     "code": "E_UNAUTHORIZED",
     "message": "Wrong username or password"
   }
 }

Logout

If you want to make the current bearer Token invalid you can logout. After call logout the bearer Token will be useless and you will need another login attempt for have a new token.

$ curl -X DELETE \
       -H "Authorization: bearer <your bearerToken>" \
       https://api.grocerest.com/v1.0/authentication

Retrieve Review of a product

When you have a bearerToken you can ask the list of reviews of a specific product. We will save your product the code you provide to us as extId. You can use this parameter in your request to retrieve all the reviews of a specific product of your database. The API will give you an error if you doesn't send a valid exitId. It will have also other parameters. Here the full list

• extId String (required) A valid unique code of your database
• from Number Will let you jump an amount of reviews. useful for the pagination
• size Number How many review you want to retrieve
• sortBy String A valid field to sort by. Valid fields are:
  • tsCreated (timestamp of creation)
  • voteCount (number of useful votes)
  • rating (rating of the review (from 1 to 5))
• sortDir String Could be asc (ascendent) or desc (descendent)

The most simple way to call this API is with just the last reviews for a product

$ curl -X POST \
       -H "Authorization: bearer 61bb8fb66e51ad375bba7a8965cdb42c" \
       -H "Content-Type: application/json" \
       -d '{"extId": "FLA071100"}' \
       https://api.grocerest.com/v1.0/partner/review-search

The answer will be like this:

{
  "count": 111,
  "average": 4.378378378378378,
  "histogram": [
    1,
    5,
    9,
    32,
    64
  ],
  "reviews": [
    ...
    {
      "product": "AVGxV_LqTpJG1XEnbYmG",
      "tsUpdated": 1477232400267,
      "author": {
        "score": 365,
        "firstname": "c*****",
        "picture": "AVfxAbhqyqGyggAv0DLZ.jpg",
        "username": "ma****024",
        "lastname": "*****",
        "_id": "AVfxAbhqyqGyggjbv0DLZ",
        "level": 2
      },
      "review": "colori belli ma poco adatti a bambini sotto 3 anni",
      "rating": 5,
      "tsCreated": 1477232374897,
      "first": false,
      "frequency": "every day",
      "_id": "AVfx6TR5yqGyggAv2KD6"
    }
    ...
  ]
}

Retrieve Summarize Information of a list of products

This API is useful when you have a list of product in your client, or in your webpage and you want to add for each product the information about the average rating and the amount of reviews. The API accept only an array of string as payload. Each string has to be a valid extId. The API will answer with an array of the same size of the one sent. If there will be an invalid extId, the api will answer for that extId like it hasn't any review.

Here there is an example how to call it. This example will ask for the informations of two products

$ curl -X POST \
       -H "Authorization: bearer 61bb8fb66e51ad375bba7a8965cdb42c" \
       -H "Content-Type: application/json" \
       -d '["FLA071100", "DEM52862V"]' \
       https://api.grocerest.com/v1.0/partner/review-mget

Calling the api like this return an array of products informations with, in this case, two product. Here the payload:

  [
    {
      "extId":"FLA071100",
      "total":111,
      "average":4.378378378378378
    },{
      "extId":"DEM52862V",
      "total":17,
      "average":4.529411764705882
    }
  ]

The next call will ask for an array with a wrong extId:

$ curl -X POST \
       -H "Authorization: bearer 61bb8fb66e51ad375bba7a8965cdb42c" \
       -H "Content-Type: application/json" \
       -d '["FLA071100", "WRONG"]' \
       https://api.grocerest.com/v1.0/partner/review-mget

the response will be as this:

  [
    {
      "extId":"FLA071100",
      "total":111,
      "average":4.378378378378378
    },{
      "extId":"WRONG",
      "total":0,
      "average":0
    }
  ]