REST API¶

Overview¶

This section shows the list of all the resources available in the LHobby REST API. Some endpoints require authentication.

Authentication

If you see this icon, the endpoint requires authentication.

If you see this icon, the endpoint does not require authentication.

Authentication¶

There are two ways to do an authenticated request.

Token: if you have an authentication token you can do an authenticated request using the header key Authorization with Token <authentication token> as value.
Cookie: if you are using a browser you can authenticate via the Cookie header key.

Login into the system. This endpoint is better suited for browser clients.

post /HOST:PORT/api/login/

Parameters

Name	Type	In	Description	Required
`username`	string	body		true
`password`	string	body		true
`next`	string	param	the url you will be redirected to	false

OK response

Status: 302 Found

Logout from the system. This endpoint is better suited for browser clients.

post /HOST:PORT/api/logout/

Parameters

Name	Type	In	Description	Required
`Cookie`	string	header	session cookie for authentication	true

OK response

Status: 200 OK

Get authorization token¶

Use this endpoint to generate a token for the authentication.

post /HOST:PORT/api/token/

Parameters

Name	Type	In	Description	Required
`username`	string	body		true
`password`	string	body		true

OK response

Status: 200 OK

{
    "token": "b8a60e83569600e8f5c323428cca736ce9176e0f"
}

Delete authorization token¶

Use this endpoint to delete a specific user token.

delete /HOST:PORT/api/token/

Parameters

Name	Type	In	Description	Required
`Authorization`	string	header	token for authentication, it must be in this form: Token	true

Response

Status: 204 No Content

API Reference¶

Create a new user¶

It allows to create a new user.

post /HOST:PORT/api/users/sign_up/

Parameters

Name	Type	In	Description	Required
`username`	string	body	the username of the user	true
`password`	string	body	the password must contain at least 8 characters and it must not be too similar to the username	true
`email`	string	body	user email	false
`first_name`	string	body	user first name	false
`last_name`	string	body	user last name	false

Created response

Status: 201 Created

{
    "username": "marta",
    "date_joined": "2021-01-18T19:08:25.023237Z",
    "elo": 1000,
    "ongoing_match": null,
    "role": null,
    "first_name": "",
    "last_name": ""
}

List users¶

List all registered users.

get /HOST:PORT/api/users/

Parameters

Name	Type	In	Description	Required
`ordering`	string	param	if equal to one in `[elo, -elo, username, -username]` the user list will be ordered	false

OK response

Status: 200 OK

[
    {
        "username": "emanuele",
        "date_joined": "2021-01-15T23:17:32.966236Z",
        "elo": 900,
        "ongoing_match": 40,
        "role": "H",
        "first_name": "",
        "last_name": ""
    },
    {
        "username": "davide",
        "date_joined": "2021-01-15T23:18:11.368676Z",
        "elo": 1000,
        "ongoing_match": null,
        "role": null,
        "first_name": "",
        "last_name": ""
    },
    {
        "username": "marta",
        "date_joined": "2021-01-18T19:08:25.023237Z",
        "elo": 1000,
        "ongoing_match": null,
        "role": null,
        "first_name": "",
        "last_name": ""
    }
]

User detail¶

Get detail of specific user using his username.

get /HOST:PORT/api/users/{username}/

Parameters

Name	Type	In	Description	Required
`username`	string	path		true

OK response

Status: 200 OK

{
    "username": "marta",
    "date_joined": "2021-01-18T19:08:25.023237Z",
    "elo": 1000,
    "ongoing_match": null,
    "role": null,
    "first_name": "",
    "last_name": ""
}

Ongoing match of a specific user¶

Get the ongoing match of a specific user.

get /HOST:PORT/api/users/{username}/ongoing_match/

Parameters

Name	Type	In	Description	Required
`username`	string	path		true

OK response

Status: 200 OK

{
    "id": 40,
    "host": {
        "username": "emanuele",
        "date_joined": "2021-01-15T23:17:32.966236Z",
        "elo": 900,
        "ongoing_match": 40,
        "role": "H",
        "first_name": "",
        "last_name": ""
    },
    "spectators": [],
    "challenger": null,
    "creation_timestamp": "2021-01-18T18:34:09.576490Z",
    "start_timestamp": null,
    "is_started": false,
    "is_challenger_ready": false
}

Create a new ongoing match¶

It allows to create a new match for the authenticated user, setting them as host of the match.

post /HOST:PORT/api/ongoing_matches/

Created response

Status: 201 Created

{
    "id": 41,
    "host": {
        "username": "marta",
        "date_joined": "2021-01-18T19:08:25.023237Z",
        "elo": 1000,
        "ongoing_match": 41,
        "role": "H",
        "first_name": "",
        "last_name": ""
    },
    "spectators": [],
    "challenger": null,
    "creation_timestamp": "2021-01-19T09:56:45.727233Z",
    "start_timestamp": null,
    "is_started": false,
    "is_challenger_ready": false
}

Warning

The user must not be already playing or spectating another match, otherwise the following response will be returned:

Status: 400 Bad Request

[
    "User davide is already in a match"
]

List ongoing matches¶

List all ongoing matches.

get /HOST:PORT/api/ongoing_matches/

Parameters

Name	Type	In	Description	Required
`ordering`	string	param	if equal to one in `[host_elo, -host_elo]` the ongoing match list will be ordered	false
`is_full`	bool	param	if true, only the matches that already have a challenger will be returned, otherwise the ones without a challenger	false
`max_elo`	number	param	if given, the ongoing matches hosted by an user with an elo greater than `max_elo` will not be returned	false
`min_elo`	number	param	if given the the ongoing matches hosted by an user with an elo less than `min_elo` will not be returned	false

OK response

Status: 200 OK

[
    {
        "id": 40,
        "host": {
            "username": "emanuele",
            "date_joined": "2021-01-15T23:17:32.966236Z",
            "elo": 900,
            "ongoing_match": 40,
            "role": "H",
            "first_name": "",
            "last_name": ""
        },
        "spectators": [],
        "challenger": null,
        "creation_timestamp": "2021-01-18T18:34:09.576490Z",
        "start_timestamp": null,
        "is_started": false,
        "is_challenger_ready": false
    },
    {
        "id": 41,
        "host": {
            "username": "marta",
            "date_joined": "2021-01-18T19:08:25.023237Z",
            "elo": 1000,
            "ongoing_match": 41,
            "role": "H",
            "first_name": "",
            "last_name": ""
        },
        "spectators": [],
        "challenger": {
            "username": "davide",
            "date_joined": "2021-01-15T23:18:11.368676Z",
            "elo": 1000,
            "ongoing_match": 41,
            "role": "C",
            "first_name": "",
            "last_name": ""
        },
        "creation_timestamp": "2021-01-19T09:56:45.727233Z",
        "start_timestamp": null,
        "is_started": false,
        "is_challenger_ready": false
    }
]

Ongoing match detail¶

Get detail of a specific ongoing match using his id.

get /HOST:PORT/api/ongoing_matches/{id}/

Parameters

Name	Type	In	Description	Required
`id`	string	path	id number of the ongoing match	true

OK response

Status: 200 OK

{
"id": 41,
"host": {
    "username": "marta",
    "date_joined": "2021-01-18T19:08:25.023237Z",
    "elo": 1000,
    "ongoing_match": 41,
    "role": "H",
    "first_name": "",
    "last_name": ""
},
"spectators": [],
"challenger": {
    "username": "davide",
    "date_joined": "2021-01-15T23:18:11.368676Z",
    "elo": 1000,
    "ongoing_match": 41,
    "role": "C",
    "first_name": "",
    "last_name": ""
},
"creation_timestamp": "2021-01-19T09:56:45.727233Z",
"start_timestamp": null,
"is_started": false,
"is_challenger_ready": false
}

Delete specific ongoing match¶

Delete a specific ongoing match given the match id.

delete /HOST:PORT/api/ongoing_matches/{id}/

Note

An ongoing match can be deleted only from its host and only if it is not started yet.

Parameters

Name	Type	In	Description	Required
`id`	string	path	id number of the ongoing match to delete	true

Response

Status: 204 No Content

Ongoing match user detail¶

Get detail of the host, the challenger or the spectators of a specific match.

get /HOST:PORT/api/ongoing_matches/{id}/{role}/

Parameters

Name	Type	In	Description	Required
`id`	string	path	id number of the ongoing match	true
`role`	string	path	choose one in `[host, challenger, spectators]`	true

OK response

Status: 200 OK

{
    "username": "davide",
    "date_joined": "2021-01-15T23:18:11.368676Z",
    "elo": 1000,
    "ongoing_match": 41,
    "role": "C",
    "first_name": "",
    "last_name": ""
}

Creation of a completed match¶

Completed matches are only automatically generated after the end of an ongoing match.

List completed matches¶

List all completed matches.

get /HOST:PORT/api/completed_matches/

Parameters

Name	Type	In	Description	Required
`ordering`	string	param	if equal to one in `[id, winner, loser, start_timestamp, end_timestamp, completion_timestamp, winner_score, loser_score, winner_elo_before_match, winner_elo_after_match, loser_elo_before_match, loser_elo_after_match]` the ongoing match list will be ordered. Put a ' - ' before the ordering type for descending order	false
`winner`	string	param	filter completed matches with a specific winner	false
`loser`	string	param	filter completed matches with a specific loser	false
`user`	string	param	filter completed matches with a specific user, it is not important if it is a winner or a loser	false
`end_timestamp_after`	datetime	param	the matches completed before the passed parameter will not be returned	false
`end_timestamp_before`	datetime	param	the matches completed after the passed parameter will not be returned	false

Note

datetime parameters must be formatted as: yy:mm:dd

OK response

Status: 200 OK

[
    {
        "id": 1,
        "winner": "davide",
        "loser": "emanuele",
        "start_timestamp": "2021-01-16T16:40:51.981401Z",
        "completion_timestamp": "2021-01-16T16:41:20.669025Z",
        "winner_score": 5,
        "loser_score": 4,
        "winner_elo_before_match": 1000,
        "loser_elo_before_match": 1000,
        "winner_elo_after_match": 1050,
        "loser_elo_after_match": 950
    }
]

Completed match detail¶

Get detail of specific completed match using his id.

get /HOST:PORT/api/completed_matches/{id}/

Parameters

Name	Type	In	Description	Required
`id`	string	path	id number of the completed match	true

OK response

Status: 200 OK

{
    "id": 1,
    "winner": "davide",
    "loser": "emanuele",
    "start_timestamp": "2021-01-16T16:40:51.981401Z",
    "completion_timestamp": "2021-01-16T16:41:20.669025Z",
    "winner_score": 5,
    "loser_score": 4,
    "winner_elo_before_match": 1000,
    "loser_elo_before_match": 1000,
    "winner_elo_after_match": 1050,
    "loser_elo_after_match": 950
}

The API REST can be used in order to create a new match or to visualize the available ongoing matches. To join a match and play or spectate it clients shall use a websocket protocol.

Next section will discuss such websocket protocol.

REST API¶

Overview¶

Authentication¶

Cookie based login¶

Parameters

OK response

Cookie based logout¶

Parameters

OK response

Get authorization token¶

Parameters

OK response

Delete authorization token¶

Parameters

Response

API Reference¶

Create a new user¶

Parameters

Created response

List users¶

Parameters

OK response

User detail¶

Parameters

OK response

Ongoing match of a specific user¶

Parameters

OK response

Create a new ongoing match¶

Created response

List ongoing matches¶

Parameters

OK response

Ongoing match detail¶

Parameters

OK response

Delete specific ongoing match¶

Parameters

Response

Ongoing match user detail¶

Parameters

OK response

Creation of a completed match¶

List completed matches¶

Parameters

OK response

Completed match detail¶

Parameters

OK response