SWDB/application/API/v1/help/api.php

<?php
/**
 * API structure definition.
 *
 * Provides the API structure to define the help page.
 *
 * @author Iñigo Valentin <i@inigovalentin.com>
 * @license https://www.gnu.org/licenses/gpl-3.0.en.html GNU General Public License V3
 * @package SWDB
 * @category API
 */

/**
 * @var mixed[] $API API help structure.
 */
$API = [
    "version" => 1,
    "category" => [
        [ // BEGIN CATEGORY Units
            "name" => "Units",
            "command" => [
                [ // BEGIN COMMAND Units
                    "name" => "units",
                    "method" => [
                        [
                            "id" => "GET",
                            "url" => "/units/",
                            "description" => "Retrieves units.",
                            "parameters" => [
                                [
                                    "key" => "page",
                                    "via" => "request",
                                    "type" => "int",
                                    "description" => "Page to fetch. Deaults to 1.",
                                    "optional" => true
                                ],
                                [
                                    "key" => "per_page",
                                    "via" => "request",
                                    "type" => "int",
                                    "description" => "number of results per page. Defaults to 30, maximum is 100.",
                                    "optional" => true
                                ],
                                [
                                    "key" => "name",
                                    "via" => "request",
                                    "type" => "string",
                                    "description" => "Filter units with this in their name. Case insensitive.",
                                    "optional" => true
                                ]
                            ],
                            "responses" => [
                                [
                                    "status" => "200",
                                    "message" => "Success.",
                                    "description" => null,
                                    "example" => null,
                                ],
                            ]
                        ],
                        [
                            "id" => "GET",
                            "url" => "/units/{id}/",
                            "description" => "Retrieves a unit info.",
                            "parameters" => [
                                [
                                    "key" => "{id}",
                                    "via" => "query",
                                    "type" => "string",
                                    "description" => "Unit ID.",
                                    "optional" => false
                                ],
                            ],
                            "responses" => [
                                [
                                    "status" => "200",
                                    "message" => "Success.",
                                    "description" => null,
                                    "example" => null,
                                ],
                                [
                                    "status" => "404",
                                    "message" => "Unit not found.",
                                    "description" => "The requested unit does not exist.",
                                    "example" => null
                                ]
                            ]
                        ],
                    ],
                ] // END COMMAND profile
            ]
        ], // END CATEGORY Units
        [ // BEGIN CATEGORY Profile
            "name" => "Profile",
            "command" => [
                [ // BEGIN COMMAND UploadProfile
                    "name" => "profile",
                    "method" => [
                        [
                            "id" => "GET",
                            "url" => "/profile/{id}/",
                            "description" => "Retrieves player profile.",
                            "parameters" => [
                                [
                                    "key" => "{id}",
                                    "via" => "query",
                                    "type" => "string",
                                    "description" => "Player ID or name.",
                                    "optional" => false
                                ],
                                [
                                    "key" => "key",
                                    "via" => "body",
                                    "type" => "string",
                                    "description" => "API key. Required for private profiles.",
                                    "optional" => true
                                ]
                            ],
                            "responses" => [
                                [
                                    "status" => "200",
                                    "message" => "Success.",
                                    "description" => null,
                                    "example" => json_encode('{"username":"IValentin","level":50,"public":"1"}', JSON_PRETTY_PRINT),
                                ],
                                [
                                    "status" => "403",
                                    "message" => "A list of profiles cant be retrieved. Please specify a profile ID or player name.",
                                    "description" => "No player ID or name has been supplied. A full list of profiles is not available.",
                                    "example" => null
                                ],
                                [
                                    "status" => "403",
                                    "message" => "The profile is not public.",
                                    "description" => "The requestd player profile is private, and the API key has not been sent or it's invalid.",
                                    "example" => null
                                ],
                                [
                                    "status" => "404",
                                    "message" => "Player not found.",
                                    "description" => "The requestd player is not registered in SWDB.",
                                    "example" => null
                                ]
                            ]
                        ],
                        [
                            "id" => "POST",
                            "url" => "/profile/{id}/",
                            "description" => "Creates a new player profile.",
                            "parameters" => [
                                [
                                    "key" => "{id}",
                                    "via" => "query",
                                    "type" => "string",
                                    "description" => "Player ID.",
                                    "optional" => false
                                ],
                                [
                                    "key" => "email",
                                    "via" => "body",
                                    "type" => "string",
                                    "description" => "User email. Must be a valid address.",
                                    "optional" => false
                                ],
                                [
                                    "key" => "password",
                                    "via" => "body",
                                    "type" => "string",
                                    "description" => "New user password.",
                                    "optional" => false
                                ],
                                [
                                    "key" => "name",
                                    "via" => "body",
                                    "type" => "string",
                                    "description" => "New username. If not supplied, it will default to 'player_[id]'. Will be overriden on the next PUT request.",
                                    "optional" => true
                                ],
                                [
                                    "key" => "public",
                                    "via" => "body",
                                    "type" => "int",
                                    "description" => "1 to make the profile public, 0 to keep it private. Default to 0.",
                                    "optional" => true
                                ],
                            ],
                            "responses" => [
                                [
                                    "status" => "201",
                                    "message" => "Created.",
                                    "description" => null,
                                    "example" => json_encode('{"username":"IValentin","email":example@example.com,"api_key":"0123456789012345","public":"0"}', JSON_PRETTY_PRINT),
                                ],
                                [
                                    "status" => "400",
                                    "message" => "User ID not received.",
                                    "description" => "The ID of the player to create is not in the query.",
                                    "example" => null
                                ],
                                [
                                    "status" => "400",
                                    "message" => "User email not received.",
                                    "description" => "The email of the player to create has not ben passed in the request.",
                                    "example" => null
                                ],
                                [
                                    "status" => "400",
                                    "message" => "Invalid email.",
                                    "description" => "The 'mail' parameter must be a valid email address.",
                                    "example" => null
                                ],
                                [
                                    "status" => "400",
                                    "message" => "User password not received.",
                                    "description" => "The password of the player to create has not ben passed in the request.",
                                    "example" => null
                                ],
                                [
                                    "status" => "400",
                                    "message" => "Existing user.",
                                    "description" => "A player with the same ID is already registered in SWDB.",
                                    "example" => null
                                ]
                            ]
                        ],
                        [
                            "id" => "PUT",
                            "url" => "/profile/{id}/",
                            "description" => "Updates a player profile with data received from the game.",
                            "parameters" => [
                                [
                                    "key" => "{id}",
                                    "via" => "query",
                                    "type" => "string",
                                    "description" => "Player ID.",
                                    "optional" => false
                                ],
                                [
                                    "key" => "key",
                                    "via" => "body",
                                    "type" => "string",
                                    "description" => "API key.",
                                    "optional" => false
                                ],
                                [
                                    "key" => "response",
                                    "via" => "body",
                                    "type" => "string",
                                    "description" => "JSON received from game server on HubUserLogin command.",
                                    "optional" => false
                                ]
                            ],
                            "responses" => [
                                [
                                    "status" => "204",
                                    "message" => "Profile imported.",
                                    "description" => null,
                                    "example" => null,
                                ],
                                [
                                    "status" => "400",
                                    "message" => "API key not received.",
                                    "description" => "No API key was suplied in the request.",
                                    "example" => null
                                ],
                                [
                                    "status" => "400",
                                    "message" => "No data received.",
                                    "description" => "Game JSON response not received from request",
                                    "example" => null
                                ],
                                [
                                    "status" => "400",
                                    "message" => "Data is no valid JSON.",
                                    "description" => "The parameter 'response' contains information, but it's not valid JSON data.",
                                    "example" => null
                                ],
                                [
                                    "status" => "401",
                                    "message" => "Invalid credentials",
                                    "description" => "The API key is not valid for the profile being updated.",
                                    "example" => null
                                ]
                            ]
                        ],
                        [
                            "id" => "DELETE",
                            "url" => "/profile/{id}/",
                            "description" => "Deletes a player profile.",
                            "parameters" => [
                                [
                                    "key" => "{id}",
                                    "via" => "query",
                                    "type" => "string",
                                    "description" => "Player ID.",
                                    "optional" => false
                                ],
                                [
                                    "key" => "key",
                                    "via" => "body",
                                    "type" => "string",
                                    "description" => "API key.",
                                    "optional" => false
                                ]
                            ],
                            "responses" => [
                                [
                                    "status" => "204",
                                    "message" => "Profile deleted.",
                                    "description" => null,
                                    "example" => null,
                                ],
                                [
                                    "status" => "400",
                                    "message" => "User ID not received.",
                                    "description" => "The ID of the player to create is not in the query.",
                                    "example" => null
                                ],
                                [
                                    "status" => "400",
                                    "message" => "API key not received.",
                                    "description" => "No API key was suplied in the request.",
                                    "example" => null
                                ],
                                [
                                    "status" => "401",
                                    "message" => "Invalid credentials",
                                    "description" => "The API key is not valid for the profile being updated.",
                                    "example" => null
                                ]
                            ]
                        ],
                    ],
                ] // END COMMAND profile
            ]
        ], // END CATEGORY Profile
        [ // BEGIN CATEGORY Run
            "name" => "Run",
            "command" => [
                [ // BEGIN COMMAND run
                    "name" => "run",
                    "method" => [
                        [
                            "id" => "POST",
                            "url" => "/run/",
                            "description" => "Logs a game run using JSON files intercepted from the game.",
                            "parameters" => [
                                [
                                    "key" => "key",
                                    "via" => "body",
                                    "type" => "string",
                                    "description" => "API key.",
                                    "optional" => false
                                ],
                                [
                                    "key" => "result_response",
                                    "via" => "body",
                                    "type" => "string",
                                    "description" => "JSON received from game server on run result.",
                                    "optional" => false
                                ],
                                [
                                    "key" => "result_request",
                                    "via" => "body",
                                    "type" => "string",
                                    "description" => "JSON sent to game server on run result. Required for commands: BattleDungeonResult_V2, BattleDimensionHoleDungeonResult_v2",
                                    "optional" => true
                                ],
                                [
                                    "key" => "start_response",
                                    "via" => "body",
                                    "type" => "string",
                                    "description" => "JSON received from game server on run start. Required for commands: BattleRiftOfWorldsRaidResult, BattleScenarioResult",
                                    "optional" => true
                                ],
                                [
                                    "key" => "start_request",
                                    "via" => "body",
                                    "type" => "string",
                                    "description" => "JSON sent to game server on run start. Required for commands: ",
                                    "optional" => true
                                ],
                            ],
                            "responses" => [
                                [
                                    "status" => "201",
                                    "message" => "Created.",
                                    "description" => null,
                                    "example" => null,
                                ],
                                [
                                    "status" => "400",
                                    "message" => "API key not received.",
                                    "description" => "No API key was suplied in the request.",
                                    "example" => null
                                ],
                                [
                                    "status" => "400",
                                    "message" => "No result response data received.",
                                    "description" => "JSON received from game server on run result wast receiven on the request.",
                                    "example" => null
                                ],
                                [
                                    "status" => "400",
                                    "message" => "Result response data is no valid JSON.",
                                    "description" => "The parameter 'result_response' contains information, but it's not valid JSON data.",
                                    "example" => null
                                ],
                                [
                                    "status" => "401",
                                    "message" => "Invalid credentials",
                                    "description" => "The API key is not valid for the profile being updated.",
                                    "example" => null
                                ],
                                [
                                    "status" => "405",
                                    "message" => "Command not implemented.",
                                    "description" => "The command referenced in the JSON file is not implemented.",
                                    "example" => null
                                ],
                                [
                                    "status" => "409",
                                    "message" => "Run already in database.",
                                    "description" => "The run is already in the database for the user.",
                                    "example" => null
                                ]
                            ]
                        ],
                    ],
                ] // END COMMAND Run
            ]
        ], // END CATEGORY Run
    ],
];