API description

As I found swagger redundant, I put it here

Consts

const DEFS = {
  PLACE: {
    ANY: 'any',
    PRODUCT: 'product',
  },
  PLACE_MODYFIER: {
    MINI: 'mini',
    SUPER: 'super',
    HYPER: 'hyper',
  },
  SOURCE_ID: {
    GOOGLE: 'google',
    YANDEX: 'yandex',
    WEB: 'web',
  },
  WEEK_DAY: {
    ANY: 'any',
    MON: 'mon',
    TUE: 'tue',
    WED: 'wed',
    THU: 'thu',
    FRI: 'fri',
    SAT: 'sat',
    SUN: 'sun',
  }
}

V1

Not to waste a lot of time, the auth protection is going to be based on hard-coded client-id sent as a header
client-token: XXXXXXXXXX, it's still half-secret value
As well there will be a kind of throttling to protect from spaming

Post a shot

POST: /api/v1/shots

Request body example

{
  "people": 10,
  "place": {
   "type": "product",
   "modifier": "super"
  },
  "source": "web",
  "shotAt": "2020-03-21T12:11:09.900+03:00",
  "trackingData": {
  	"sessionId": "some_kind_of_user_identifier",
  	"sourceId": "web"
  }
}

• people 0..100
• place->>type always product (means Product Store, that's only one allowe option for now)
• place->>modifier (mini / super / hyper)
• source always web for web, google, yandex, android, ios
• shootedAt we have to take care about timezone only, and we can get the date/time itself based on the UTC of a server
• trackingData->>sessionId must be produced by front, TBD
• trackingData->>sourceId always web for web, google, yandex, android, ios
• Everything is required

Response

OK: 201

403 if the client-id is wrong

400 if an invalid body

Get filtered stats

GET: /api/v1/stats/

• example /api/v1/stats?place=product&placeModifier=super&weekDay=Any&moment=2020-03-21T12:11:09
• the client id header is still required
• to get a moment stats call like /api/v1/stats?moment=2020-03-21T12:11:09+03:00

Params:

• place can be product or any
• placeModifier can be mini,super,hyper,any
• weekDay can be any,mon,tue,wed,thu,fri,sat,sun
• moment can be ISO time, conflicts with weekDay, do not use both to get correct result

Response OK: 200

{
 "hours": [
    {
      "name": "00:00",
      "val": 0.2,
    },
    {
      "name": "01:00",
      "val": 0.09,
    },
    ... till 23:00
 ],
 "halves": [
    {
      "name": "00:00",
      "val": 0.2,
    },
    {
      "name": "00:30",
      "val": 0.12,
    },
    ... till 23:30
 ]
}

403 if the client-id is wrong

Internal [parsing service] add a place

POST: /api/v1/places

Request body example

{
  "type": "product",
  "modifier": "super",
  "name": "Green",
  "address": "\u0422\u0426 \u0421\u043a\u0430\u043b\u0430, Ulitsa Petra Glebki 5, Minsk, Belarus",
  "coordinate": {
    "lat": 53.90827480000001,
    "lng": 27.4697201
  }
}

Response

OK: 201

{
    "id": 4,
    "name": "Green",
    "type": "product",
    "modifier": "super",
    "address": "ТЦ Скала, Ulitsa Petra Glebki 5, Minsk, Belarus",
    "coordinate": {
        "id": 3,
        "lat": 53.90827480000001,
        "lng": 27.4697201
    }
}

403 if the client-id is wrong

400 if an invalid body

Internal [parsing service] making shots

POST: /api/v1/places/{id}/shots

Request body example

{
  "people": 10,
  "shotAt": "2020-03-21T12:11:09+03:00",
  "source": "google",
  "trackingData": {
  	"sourceId": "google"
  }
}

Response

OK: 201

403 if the client-id is wrong

404 if the place isn't found

400 if an invalid body

Internal [parsing service] get places

GET /api/v1/places?name=removeme&address=ТЦ Скала, Ulitsa Petra Glebki 5, Minsk, Belarus&lat=42.03&lng=42.059679

The filters (get params) are not required

Response

OK: 200

[
    {
        "id": 12,
        "name": "Removeme",
        "type": "product",
        "modifier": "hyper",
        "address": "Somewhere",
        "coordinate": {
            "id": 7,
            "lat": 42.0,
            "lng": 42.02
        }
    }
]

403 if the client-id is wrong

400 if an invalid body