backend for stayathome

table of contents

1. setup
   1. installation
   2. conventions
2. base url
3. api documentation
   1. account management
      1. authorization
      2. get user stats
      3. create entered home event
      4. create left home event
      5. get user
      6. create user
      7. add points
   2. leaderboard
      1. get leaderboard
      2. get leaderboard by nation

setup

The API is built with Lumen, Laravel's micro framework (PHP). To understand the basics, follow the official documentation. A simple dev environment for Mac can be setup with Laravel Valet.

Installation

1. make sure you have PHP, SQL (My, Maria, Postgres, SQLite), composer and phpunit installed
2. clone the repository
3. in your project root run composer install
4. setup a sql-style database
5. copy the .env.example to a .env file, set APP_KEY, APP_NAME, APP_URL and database credentials DB_CONNECTION DB_HOST DB_PORT DB_DATABASE DB_USERNAME DB_PASSWORD
6. in your project root run php artisan migrate
7. in your project root run php artisan jwt:secret to generate JWT_SECRET environment variable

You're all set.

Conventions

This project follows the approach of TDD (as good as possible in the scope of a hackathon). When you create new code, make sure to write phpunit tests before.

base url

wirvsvirus.agile-punks.com

https://wirvsvirus.agile-punks.com/

headers

required on post requests.

content-type: application/json

api documentation

account management

authorization

POST login | 200 OK | 422 on validation error | 401 Unauthorized

// payload
{
    "username":  "<some username>",
    "password":  "<some password>"
}

//response
{
    "token": "eyJ0eX123iJKV1QiLCJhbGciOiJIUzI1NiJ9.123pc3MiOiJodHRwOlwvXC9sb2NhbGhvc3Q6O123MFwvbG9naW4iLCJpYXQiOjE1ODQ5NzU3NzgsImV4cCI6MTU4NDk3OTM3OCwibmJmIjoxNTg0OTc1Nzc4LCJqdGkiOiJZY0NQSEdxNG1IM2Q1clBuIiwic3ViIjoxMTQ1LCJwcnYiOiIzNzg3ZmJhMTYxOGE5MzA1MjZhY2E2YzhiYjliNDRiODNmMjk3NzI2In0.Ek40iSSXvzlr63Ec0k8tHtQTuYwpkQ123yv1RWYWaHA",
    "token_type": "bearer",
    "expires_in": 3600
}

get user stats

GET users/<username>/stats | 200 OK | 404 on not found

//response
{
    "seconds": 124513235,
    "points": 1341
}

create entered home event

POST users/<username>/home-enter | 201 Created | 422 on validation error | 404 on not found

// payload
{
    "timestamp": "2020-03-21T10:50:22.000000Z"
}

//response
{
    "entered": "2020-03-21 10:50:22",
    "token": "9ce46249294e220f06434d57911a7c4a", //used for home-leave reference
    "updated_at": "2020-03-21T11:33:36.000000Z",
    "created_at": "2020-03-21T11:33:36.000000Z"
}

create left home event

POST users/<username>/home-leave | 201 Created | 422 on validation error | 404 on not found

// payload
{
	"timestamp": "2020-03-21T15:50:22.000000Z",
	"token": "9ce46249294e220f06434d57911a7c4a"
}

//response
{
    "entered": "2020-03-21T10:50:22.000000Z",
    "left": "2020-03-21T15:50:22.000000Z",
    "token": "9ce46249294e220f06434d57911a7c4a",
    "created_at": "2020-03-21T14:43:30.000000Z",
    "updated_at": "2020-03-21T14:44:44.000000Z"
}

get user

GET users/<username> | 200 OK | 404 on not found

//response
{
    "seconds": 124513235,
    "points": 1341,
    "username": "<some username>",
    "display_name": "<some display name>",
    "created_at": "2020-03-21T09:32:39.000000Z",
    "updated_at": "2020-03-21T09:32:39.000000Z",
    "nation": "Deutschland",
    "city": "Berlin"
}

create user

POST users | 201 Created | 422 on validation error

// payload
{
    "username": "<unique username>",
    "display_name": "<some display name>",
    "nation": "de", //optional country code
    "city": "Berlin" //optional
}

//response
{
    "username": "raphbibus204",
    "display_name": "Ralph",
    "points": 0,
    "seconds": 0,
    "nation": "de",
    "city": "Berlin",
    "updated_at": "2020-03-21T19:41:02.000000Z",
    "created_at": "2020-03-21T19:41:02.000000Z"
}

add points

POST users/<username>/points-add | 201 Created | 422 on validation error | 404 on not found

// payload
{
    "points": 400 //some integer
}

//response
{
    "username": "raphbibus204",
    "display_name": "Ralph",
    "created_at": "2020-03-21T21:30:31.000000Z",
    "updated_at": "2020-03-21T21:30:55.000000Z",
    "seconds": 0,
    "points": 3400,
    "nation": "de",
    "city": "Berlin"
}

leaderboard

get leaderboard

GET leaderboard | 200 OK

//response
{
    "current_page": 1,
    "data": [
        {
            "username": "wehner.gregorio",
            "display_name": "Mrs. Rosalyn Bashirian",
            "created_at": "2020-03-21T19:27:40.000000Z",
            "updated_at": "2020-03-21T19:27:40.000000Z",
            "seconds": 34399,
            "points": 196153,
            "nation": "id",
            "city": "West Kaelynchester"
        },
        //further results, 20 per page
        {
            "username": "luigi39",
            "display_name": "Katarina Feeney",
            "created_at": "2020-03-21T19:27:40.000000Z",
            "updated_at": "2020-03-21T19:27:40.000000Z",
            "seconds": 1242550,
            "points": 115899,
            "nation": "ms",
            "city": "Caseyberg"
        }
    ],
    "first_page_url": "https://wirvsvirus.agile-punks.com/leaderboard?page=1",
    "from": 1,
    "last_page": 3,
    "last_page_url": "https://wirvsvirus.agile-punks.com/leaderboard?page=3",
    "next_page_url": "https://wirvsvirus.agile-punks.com/leaderboard?page=2",
    "path": "https://wirvsvirus.agile-punks.com/leaderboard",
    "per_page": 20,
    "prev_page_url": null,
    "to": 20,
    "total": 54
}

get leaderboard by nation

GET leaderboard/nation/<simple locale> | 200 OK

A simple locale would be "de" for Germany or "it" for Italy.

//response
{
    "current_page": 1,
    "data": [
        {
            "username": "stoltenberg.lawrence",
            "display_name": "Tomas Veum",
            "created_at": "2020-03-22T11:06:17.000000Z",
            "updated_at": "2020-03-22T11:06:17.000000Z",
            "seconds": 233405,
            "points": 194177,
            "nation": "de",
            "city": "München"
        },
        //further results, 20 per page
        {
            "username": "joaquin.kutch",
            "display_name": "Merle Schoen III",
            "created_at": "2020-03-22T11:06:17.000000Z",
            "updated_at": "2020-03-22T11:06:17.000000Z",
            "seconds": 524157,
            "points": 91921,
            "nation": "de",
            "city": "Treppendorf"
        }
    ],
    "first_page_url": "https://wirvsvirus.agile-punks.com/leaderboard/nation/de?page=1",
    "from": 1,
    "last_page": 2,
    "last_page_url": "https://wirvsvirus.agile-punks.com/leaderboard/nation/de?page=2",
    "next_page_url": "https://wirvsvirus.agile-punks.com/leaderboard/nation/de?page=2",
    "path": "https://wirvsvirus.agile-punks.com/leaderboard/nation/de",
    "per_page": 20,
    "prev_page_url": null,
    "to": 20,
    "total": 36
}