1.- API Documentation

Calling the API

The URL to make all the requests in our API starts with https://7eb5gyaxdc.execute-api.eu-west-1.amazonaws.com/prod. Moreover, in order to call the methods you need the API key, a unique key to authenticate in our servers. To know your API you must log in your dashboard and, inside the section Settings you will find a specific section to work with our SDK.


The API is protected by the standard protocol OAuth2 that allows the applications to access in a delimited way the data placed in the API in the name of the user without the need of giving access credentials (user/password, etc). Therefore, apart from the API Key, requests must also have the Bearer Token included to authorize the calls. In order to get the Token, we must always make a user login that will send that token back and will serve to access the requests.


The current version of Hooptap’s API is 2.0.0. Hooptap does a versioning of its API following semantic versioning (semVer) which allows to have working both the current and the previous versions in an organized and easy way. This allows our clients to use them and make sure that there is no compatibility problem in an upgrade.


When we make a request to the API we can use several parameters to define and filter the data it sends back. Requests would be made in the following way (data sent in the filters must be codified to embed in the URL, for example we can use this online tool: URL Encoder):


This can be an example with all the data:


And once passed through an URL encoder it would look like this:

whereJSON ObjectFilter query sent to the server
A key is used for each field you want to use as a filter.

value : Value of the filter.
search_type : Type of query allowed [“include”], if this field is not included an exact query of the value will be made.
It will look for users whose username is John

“username” : {
“value” : “John”

It will look for users whose username includes John

username : {
“value” : “John”,
“search_type” : “include”

It will look for user whose username contains John or is exactly Jane

username : [{
“value” : “John”,
“search_type” : “include”
“value” : “Jane”
includeJSON ArrayIt allows to include specific fields sent back by a query, for example if in one document we have the user ID, we can ask for it to be substituted by the user’s information

path : nname of the field sent back by the query, which will be substituted by the document it points to.
select : field of the included document that we want to request, separated by 1 space
User id will be substituted by the user file with the fields username and email and the reward id will be also substituted for the document containing its name and image
"include" : [
"path" : "user",
"select" : "username email"
"path" : "reward",
"select" : "name image"
It allows to sort a result, it has a key for each field we want to sort, and a string value with the values “asc” and “desc”Sorting by name in ascending order
"sort" : {
"name" : "asc"
groupStringIt allows to group results by a field
(SQL’s groupBy)
Group results by user id
"group" : "user_id",
fieldsStringFields you want to request in a file
Field names separated by 1 space
The less fields you require, the faster will be the request executed
Request the field username and user email
"fields" : "username email",


The API allows to paginate results to show them in a better order for users. To do it we must add two more parameters in the request:

page_numberNumberNumber of pages you want"page_number" : "1"
page_sizeNumberNumber of elements per page"page_size" : "10"

In the response obtained, several parameters are sent to make page management easier, so in each paginated request the url of the next page is delivered back (next), and also the total amount of items of the response (item_count), the current page (current_page), the amount of items per page (page_size) and the overall amount of pages (total_pages).

"paging": {
      "current_page": 6,
      "page_size": 10,
      "total_pages": 15,
      "item_count": 143
    "next": "?page_number=7"


Responses of our API are always in JSON format, and have the following fields:

CodeThe code sent back by the sent request. This code is different to the one on the headers. This is a code that, in case of contacting Hooptap managers, must be communicated for us to quickly identify the error.
MessageA message that explains the type of response in an understandable way.
timeDate in which the response took place in ISO-date in a complete plus format.
timestampDate in which the response took place in timestamp format.
responseIn case the response is correct, data corresponding to the call will appear here.

This is an example of the response to a correct request to the API:

  "code": "0000",
  "message": "Success",
  "time": "2016-02-18T17:04:33.581Z",
  "timestamp": 1455815073581,
  "response": {
  "items": [
        "_id": "56bb6776c4c5ad144da07c9b",
        "password": "$2a$05$O8vKbzu6lNle.7GtmiSWvuF5YCAQv6a/1GzCzam/ZCqUG",
        "email": "user1@hooptap.com",
        "product": "",
        "creation_date": "2001-02-10T16:37:59.663Z",
        "gender": 0,
        "image": "https://hooptap.s3.amazonaws.com/user_profiles/tapface.jpg",
        "phone_number": "",
        "postal_code": "",
        "surname": "",
        "username": "User 1",
        "external_id": "",
        "__v": 0
"paging": {
      "current_page": 1,
      "page_size": 5,
      "total_pages": 1,
      "item_count": 1
    "next": "/user?page_number=2"

When a request sends back a failed response, it maintains the same format, where we find the message explaining the error, the error identifier and the httpError (List of codes for responses)

This is an example of a response to a failed request to the API:

  "message": "User not found",
  "errorId": "56c5fc4f8bd251c61c994b96",
  "httpErrorCode": 404,
  "time": "2016-02-18T17:15:59.101Z",
  "timestamp": 1455815759101