Detailed Report on API Endpoints for Game UI Development - wwestlake/Labyrinth GitHub Wiki

Detailed Report on API Endpoints for Game UI Development

Introduction

This report provides a comprehensive overview of the API endpoints used in the game application. Each endpoint serves a specific purpose, such as managing characters, items, item instances, item prototypes, commands, processes, rooms, and user data. The report details the usage, required inputs, expected outputs, and how these endpoints integrate with the user interface (UI) components to facilitate a seamless gaming experience.

Endpoint Overview

1. Character Endpoints

1.1 POST /api/Character/Generate

  • Purpose: Generates a new character in the game.
  • Usage: This endpoint is used when a player creates a new character, selecting attributes such as name, class, and race.
  • Data Input:
    • Request Body: 
      {
  "name": "string",
  "characterClass": 0,  // Enum representing character class
  "race": 0            // Enum representing character race
}
  • Data Output:
    • Response Body: On success, this endpoint typically returns a status 200 with the newly created character's details, including an ID, name, class, race, stats, and inventory information.

1.2 PUT /api/Character/Update/{id}

  • Purpose: Updates the stats of an existing character.
  • Usage: Utilized when a player's character's attributes or statistics are modified due to gameplay events or player decisions.
  • Data Input:
    • Path Parameter:
      • id: Character ID (string)
    • Request Body: 
      {
  "updatedStats": {
    "strength": 10,
    "agility": 5,
    "intelligence": 8
  }
}
  • Data Output:
    • Response Body: A status code 200 on successful update with a confirmation message or the updated character details.

1.3 PATCH /api/Character/UpdateNameDescription/{id}

  • Purpose: Updates the character's name and description.
  • Usage: Used when a player wants to change the character's name or description.
  • Data Input:
    • Path Parameter:
      • id: Character ID (string)
    • Request Body: 
      {
  "name": "string",
  "description": "string"
}
  • Data Output:
    • Response Body: A status code 200 on successful update with a confirmation message.

2. Command Endpoints

2.1 POST /api/Command/execute-command

  • Purpose: Executes a specific game command inputted by the player.
  • Usage: This endpoint is critical for processing player actions like moving between rooms, using items, or interacting with game objects.
  • Data Input:
    • Request Body: JSON object containing command details, e.g., 
      {
  "command": "move north"
}
  • Data Output:
    • Response Body: A JSON object detailing the result of the command execution, such as the outcome of moving rooms or the result of using an item.

3. DevAuth Endpoints

3.1 POST /api/dev-auth/custom-token

  • Purpose: Generates a custom authentication token for developers.
  • Usage: Primarily used during development or testing to simulate user authentication without requiring full login procedures.
  • Data Input:
    • Request Body: 
      {
  "userId": "string",
  "role": "string"  // Role of the user (e.g., "Admin", "Player")
}
  • Data Output:
    • Response Body: A status code 200 and a JSON object containing the generated custom token.

3.2 POST /api/dev-auth/exchange-token

  • Purpose: Exchanges a custom token for a session token.
  • Usage: Used to authenticate sessions during development with a custom token.
  • Data Input:
    • Request Body: 
      {
  "customToken": "string"
}
  • Data Output:
    • Response Body: A status code 200 and a JSON object with the session token details.

4. Item Endpoints

4.1 GET /api/Item

  • Purpose: Retrieves a list of all items available in the game.
  • Usage: Used by the game UI to display available items, such as in an inventory or store interface.
  • Data Input: No input parameters required.
  • Data Output:
    • Response Body: A JSON array of item objects, each containing: 
      [
  {
    "id": {
      "timestamp": 0,
      "creationTime": "2024-08-29T13:14:37.322Z"
    },
    "type": 0,
    "name": "string",
    "description": "string"
  }
]

4.2 POST /api/Item

  • Purpose: Creates a new item.
  • Usage: Used when adding new items to the game, such as through admin actions or item creation scripts.
  • Data Input:
    • Request Body: 
      {
  "id": {},
  "type": 0,
  "name": "string",
  "description": "string"
}
  • Data Output:
    • Response Body: A JSON object containing the newly created item's details.

4.3 GET /api/Item/{id}

  • Purpose: Retrieves the details of a specific item by ID.
  • Usage: Accessed when a player views an item in their inventory or examines an item in the game world.
  • Data Input:
    • Path Parameter:
      • id: Item ID (string)
  • Data Output:
    • Response Body: A JSON object containing the item details.

4.4 PUT /api/Item/{id}

  • Purpose: Updates an existing item.
  • Usage: Used by admins or game logic to modify item attributes.
  • Data Input:
    • Path Parameter:
      • id: Item ID (string)
    • Request Body: 
      {
  "id": {},
  "type": 0,
  "name": "string",
  "description": "string"
}
  • Data Output:
    • Response Body: A status code 200 on successful update.

4.5 DELETE /api/Item/{id}

  • Purpose: Deletes an item by ID.
  • Usage: Admin or system use only, for removing items no longer needed in the game.
  • Data Input:
    • Path Parameter:
      • id: Item ID (string)
  • Data Output:
    • Response Body: A status code 200 on successful deletion.

5. ItemInstances Endpoints

5.1 POST /api/ItemInstances

  • Purpose: Creates a new instance of an item.
  • Usage: Used when a player acquires an item, creating an instance tied to their character or inventory.
  • Data Input:
    • Request Body: 
      {
  "id": {},
  "prototypeId": {},
  "ownerId": "string",
  "weight": 0
}
  • Data Output:
    • Response Body: A status code 200 with the new item instance details.

5.2 GET /api/ItemInstances

  • Purpose: Retrieves a list of all item instances.
  • Usage: Used by the game to display all instances of items, typically for admin purposes.
  • Data Input: No input parameters required.
  • Data Output:
    • Response Body: A JSON array of item instance objects.

5.3 GET /api/ItemInstances/{id}

  • Purpose: Retrieves a specific item instance by ID.
  • Usage: Used when viewing or interacting with a specific item in the player's inventory.
  • Data Input:
    • Path Parameter:
      • id: Item Instance ID (string)
  • Data Output:
    • Response Body: A JSON object with item instance details.

5.4 PUT /api/ItemInstances/{id}

  • Purpose: Updates an existing item instance.
  • Usage: Used when modifying the properties of an item instance, such as during gameplay when an item is used or altered.
  • Data Input:
    • Path Parameter:
      • id: Item Instance ID (string)
    • Request Body: 
      {
  "id": {},
  "prototypeId": {},
  "ownerId": "string",
  "weight": 0
}
  • Data Output:
    • Response Body: A status code 200 on successful update.

5.5 DELETE /api/ItemInstances/{id}

  • Purpose: Deletes an item instance by ID.
  • Usage: Admin or system use only, for removing item instances no longer needed.
  • Data Input:

    • Path Parameter: