Skip to content

Latest commit

 

History

History
196 lines (139 loc) · 4.06 KB

README.md

File metadata and controls

196 lines (139 loc) · 4.06 KB

HTL Catcher Leaderboard API

We have set up a RESTful API in order to access leaderboard data inside the HTL Catcher Android app. This document lists all existing API nodes/resources and describes how to use them.

All API URLs are prefixed with /api/. Due to the fact that this project is a very small and is maybe used just once in production, the API does not support versions.

Table of contents

Authorization

Some API nodes (especially the POST ones) require authorization by the user. The API uses Basic auth, usernames and salted SHA-512 password hashes for API users are stored in /webserver/static/users.json. After you have added a user plus a password hash generated using the generate_hash.py script there, you can use Basic auth.

Nodes which require authorization are marked as such.

Authorization Example

Username: peter
Password: supersecurepassword
  1. Generate a hash for the chosen password
user@pc:/htl-catcher/server$ py generate_hash.py supersecurepassword
  1. Enter the user data in users.json
[
    {
        "name": "peter",
        "password_hash": "c18c24d6a99817142d20db895b1b478cd0d0af16bc09e6d1adae33795afbd357633fc57549b19c61bee7e6dd30871c43c2d9bfe818323e6e432fd5ce876a4ab0bc992d18bc82330b46860e5045700349ab82715576e8524e545983454e06e366"
    }
]
  1. Use Basic authorization header

peter:supersecretpassword encoded in Base64 is cGV0ZXI6c3VwZXJzZWNyZXRwYXNzd29yZA==

Authorization: Basic cGV0ZXI6c3VwZXJzZWNyZXRwYXNzd29yZA==

Nodes

Add

Modifies the remote leaderboard data by adding a new player entry to the leaderboard.

POST /add

Requires Authorization: Yes

Headers

Authorization: Basic b64<username:password>
Content-Type: application/json

Payload

  • name: string — required
  • score: integer — required
  • message: string
{
    "name": "Freddie Mercury",
    "score": 1970,
    "message": "Don't stop me now"
}

Success response

{
    "message": "Successfully added new leaderboard entry."
}

Example call

user@pc:~$ curl --location --request POST '/api/add' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic cGV0ZXI6c3VwZXJzZWNyZXRwYXNzd29yZA==' \
--data-raw '{
    "name": "Freddie Mercury",
    "score": 1970,
    "message": "Don'\''t stop me now"
}'

Remove

Modifies the remote leaderboard data by removing all occurrences of a received player name.

POST /remove

Requires Authorization: Yes

Headers

Authorization: Basic b64<username:password>
Content-Type: application/json

Payload

  • name: string — required
{
    "name": "Freddie Mercury"
}

Success response

{
    "message": "Successfully removed leaderboard entry / entries."
}

Example call

user@pc:~$ curl --location --request POST '/api/remove' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic eWVldDpuaWNvbGF1cw==' \
--data-raw '{
    "name": "Freddie Mercury"
}'

Fetch

Queries the remote leaderboard data by position. Lowest position = player with the highest score. If no argument is provided, the API sends the first 10 leaderboard entries

GET /fetch

Requires Authorization: No

Headers

Content-Type: application/json

Payload

  • position: integer
{
    "position": 0
}

Success response

{
    "message": "Don't stop me now",
    "name": "Freddie Mercury",
    "score": 1970
}

Example call

user@pc:~$ curl --location --request POST '/api/remove' \
--header 'Content-Type: application/json' \
--data-raw '{
    "position": 0
}'

Contribute

Documentation is important. If you contribute to this project and want to add a new API node / resource, please add appropriate documentation for it to this file.