Requests - ignacioch/GameSetMatch.firebase GitHub Wiki

Most of the requests should be commented in main.py

• Register Player
• Create League
• Start Round
• Add Player to a League

Register Player

def registerPlayer(req: https_fn.Request) -> https_fn.Response:
    """
    Registers a new player and adds their information to the Firestore database.
    
    This function parses JSON data from the incoming HTTP POST request and creates
    a new player entry in Firestore. The JSON payload must include the following fields:
    - name (str): The name of the player.
    - email (str): The email of the player.
    - DOB (str): The date of birth of the player, in "YYYY-MM-DD" format.
    - level (str): The skill level of the player.
    - areas (list of str, optional): An array of strings, each representing an area ID where the player is interested in participating.

    Args:
        req (https_fn.Request): The request object containing JSON data with the player's information.

    Returns:
        https_fn.Response: A JSON response containing the newly created player's data,
        including their unique Firestore ID, or an error message with an appropriate
        HTTP status code on failure. The response includes the player's name, email,
        date of birth (DOB), level, and areas of interest.
    """

Example request :

curl -X POST [API_ENDPOINT]/registerPlayer \
-H "Content-Type: application/json" \
-d '{
      "name": "John Doe",
      "email": "[email protected]",
      "DOB": "1990-01-01",
      "level": "beginner",
      "areas": ["North City", "South City"]
    }'

Create League

def createLeague(req: https_fn.Request) -> https_fn.Response:
    """
    Endpoint to create a league. This is meant to be called for just creating a new League

    Args:
        req (https_fn.Request): The request object containing JSON data.

    Fields:
        - league_name (str): The name of the league to be created.
        - area_id (str): The identifier of the area where the league is located.
        - start_date (str): The start date of the league, in "YYYY-MM-DD" format.
        - end_date (str): The end date of the league, in "YYYY-MM-DD" format.

    Returns:
        https_fn.Response: A JSON response containing the newly created league's details,
        including its unique Firestore ID and other provided information,
        or an error message with an appropriate HTTP status code on failure.
    """
    return api.createLeague(req)

Example Request

curl -X POST [API_ENDPOINT]/createLeague \
-H "Content-Type: application/json" \
-d '{
    "league_name": "North City League",
    "area_id": "area123",
    "start_date": "2024-01-01",
    "end_date": "2024-12-31"
}'

startRound

@https_fn.on_request()
def startRound(req: https_fn.Request) -> https_fn.Response:
    """
    Starts a new round in a league, creating groups from unallocated players.

    This function initiates a new round in a league specified by the league_id in the request.
    It checks if there are unallocated players in the league; if so, it organizes these players into groups
    based on their levels and updates the league's current round and status to running. The function also
    ensures that leagues without unallocated players do not start a new round and returns an error instead.

    Args:
        req (https_fn.Request): The request object containing JSON data.

    Fields:
        - league_id (str): The unique identifier of the league for which to start a new round.

    Returns:
        https_fn.Response: A JSON response containing information about the update, including:
        - A success message and details of the new round if the operation is successful.
        - An error message with an appropriate HTTP status code if the operation fails,
          such as when there are no unallocated players or the league does not exist.

    Raises:
        ValueError: If the league does not have unallocated players or if the league_id does not correspond to an existing league.
    """
    return api.startARound(req)

Example Request

curl -X POST [API_ENDPOINT]/startRound \
-H "Content-Type: application/json" \
-d '{
    "league_id": "league123"
}'

Add Player to a League

A player gets added to the league and waiting until the new round gets started.

@https_fn.on_request()
def addPlayerToLeague(req: https_fn.Request) -> https_fn.Response:
    """
    Endpoint to add a player to a league.

    Expects a POST request with a JSON payload containing 'player_id' and 'league_id'.
    Adds the player to the specified league and updates the league's list of players.

    Args:
        req (https_fn.Request): The request object containing JSON data.

    Fields:
        - player_id (str): The ID of the player
        - league_id (str): The ID of the league they are entering

    Returns:
        https_fn.Response: A JSON response confirming the addition of the player to the league,
        or an error message with an appropriate HTTP status code on failure.
    """
    return api.addPlayerToLeague(req)

Example request

curl -X POST "http://localhost:5001/your-project-id/us-central1/addPlayerToLeague" \
     -H "Content-Type: application/json" \
     -d '{
           "player_id": "player123",
           "league_id": "league456"
         }'