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

<?php

    /**
     * @var mixed[] $API API help structure.
     */
    $API = [
        "version" => 2,
        "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
        ],
    ];
?>