diff --git a/Docs/API/README.md b/Docs/API/README.md new file mode 100644 index 0000000..de769a8 --- /dev/null +++ b/Docs/API/README.md @@ -0,0 +1,25 @@ +# API Documentation + +## Introduction + +This API provides CRU (Create, Read, Update) operations for various models. + +The API requires an API key for some operations. + +The endpoints provided by this API are: + +## Generic: +- / - List all routes (JSON Response) +- /ping - Returns pong +- /stats - Simple stats about the bot (Record counts and uptime) +- /most-recent-drop - Returns the most recent drop (Requires API Key) + +## For characters: +- [`/characters`](api/characters.md#get-characters) +- [`/characters/:character_id`](api/characters.md#get-characterscharacter_id) + +## For groups: +_TODO_ + +## For Badges: +_TODO_ \ No newline at end of file diff --git a/Docs/API/characters.md b/Docs/API/characters.md new file mode 100644 index 0000000..2c033b8 --- /dev/null +++ b/Docs/API/characters.md @@ -0,0 +1,216 @@ +# Character endpoints + +# GET /characters + +Retrieves a list of Characters. + +#### Query Parameters + +- `include_disabled` (optional, boolean): If set to `true`, disabled characters will also be returned. +(Requires API Key) + +## Response +### Success Response + +- Status Code: `200` +- Content-Type: `application/json` + +Returns an array of Character objects. Each object contains the following fields: + +- `id` (integer): The ID of the character. +- `name` (string): The name of the character. +- `description` (string): A description of the character. +- `enabled` (boolean): A flag indicating whether the character is enabled. +- `createdAt` (string): The date and time when the character was created. +- `updatedAt` (string): The date and time when the character was last updated. +- `GroupId` (integer): The ID of the group that the character belongs to. + +#### Error Response + +- Status Code: `500` +- Content-Type: `application/json` + +Returns an object containing an error message. + +
Example + +Request: +``` +GET /characters +``` +Response: +```json +[ + { + "id": 1, + "name": "GUMI", + "groupId": 2, + "imageIdentifier": "vocaloid/gumi.jpg", + "description": "A Vocaloid created by INTERNET Co. based on the voice of Megumi Nakajima.", + "enabled": true, + "createdAt": "2022-09-07T13:27:17.000Z", + "updatedAt": "2023-01-12T18:52:03.000Z", + "GroupId": 2 + }, + { + "id": 2, + "name": "IA", + "groupId": 2, + "imageIdentifier": "vocaloid/ia.jpg", + "description": "IA is a character and voice created by 1st Place for the Vocaloid 3 speech synthesizer software. She was released in January 2012, and made her video game in 2013's Demon Gaze, providing the vocals for the game's soundtrack as well being a recruitable party member via DLC.", + "enabled": true, + "createdAt": "2022-09-07T13:27:17.000Z", + "updatedAt": "2023-01-12T18:52:03.000Z", + "GroupId": 2 + } +] + +``` +
+ + +# POST /characters + +Creates a new character. + +### Request Headers +The request headers should include an `Authorization` header with a valid API Key. + +### Request Body +The request body should be a JSON object that contains the following fields: +- `name` (required, string): The name of the character. +- `groupId` (required, integer): The ID of the group that the character belongs to. +- `imageIdentifier` (required, string): The identifier of the character's image file. +- `description` (optional, string): A description of the character. + +## Response +### Success Response +- Status Code: `201` +- Content-Type: `application/json` + +Returns an object containing the following fields: +- `message` (string): A success message. +- `character` (object): The created Character object. + +### Error Response +- Status Code: `500` +- Content-Type: `application/json` + +Returns an object containing the following fields: +- `message` (string): An error message. +- `error` (object): The error object. + +
Example + +Request: +```json +POST /characters +Content-Type: application/json + +{ + "name": "GUMI", + "groupId": 2, + "imageIdentifier": "vocaloid/gumi.jpg", + "description": "A Vocaloid created by INTERNET Co. based on the voice of Megumi Nakajima." +} +``` +Response: +```json +{ + "message": "Character created successfully.", + "character": { + "id": 1, + "name": "John Doe", + "description": "A mysterious and enigmatic character.", + "enabled": false, + "createdAt": "2023-04-17T12:00:00.000Z", + "updatedAt": "2023-04-17T12:00:00.000Z", + "GroupId": null + } +} +``` +
+ +# GET /characters/:character_id + +Returns a single character. + +## Response +### Success Response + +- Status Code: `200` +- Content-Type: `application/json` + +Returns an object of a Character with the following fields: + +- `id` (integer): The ID of the character. +- `name` (string): The name of the character. +- `description` (string): A description of the character. +- `enabled` (boolean): A flag indicating whether the character is enabled. +- `createdAt` (string): The date and time when the character was created. +- `updatedAt` (string): The date and time when the character was last updated. +- `GroupId` (integer): The ID of the group that the character belongs to. + +#### Error Response + +- Status Code: `500` +- Content-Type: `application/json` + +Returns an object containing an error message. + +
Example + +Request: +``` +GET /characters/1 +``` +Response: +```json +{ + "id": 1, + "name": "GUMI", + "groupId": 2, + "imageIdentifier": "vocaloid/gumi.jpg", + "description": "A Vocaloid created by INTERNET Co. based on the voice of Megumi Nakajima.", + "enabled": true, + "createdAt": "2022-09-07T13:27:17.000Z", + "updatedAt": "2023-01-12T18:52:03.000Z", + "GroupId": 2 +} +``` +
+ +# PUT /characters/:character_id + +Updates an existing character. + +### Endpoint +`/characters/:character_id` + +- `:character_id` (integer): The ID of the character to update. + +### Request Headers +The request headers should include an `Authorization` header with a valid API Key. + +### Request Body +The request body should be a JSON object that contains the fields to be updated. + +
Example + +Request: +```json +PUT /characters/1 +Content-Type: application/json + +{ + "imageIdentifier": "vocaloid/gumi_new.jpg", + "description": "An updated description. Lorem ipsum dolor sit kebab" +} +``` +Response: +```json +{ + "message": "Character updated successfully." +} +``` +
\ No newline at end of file diff --git a/README.md b/README.md index 75d7714..9662a36 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Band Bot +# Toho Miku ### Run dev container @@ -13,6 +13,5 @@ $npx sequelize db:migrate $npx sequelize db:seed:all ``` -### Import - -Use `npm run import` to import from assets/import/{bands,characters}. +### API +API docs can be found in [Docs/api/README.md](Docs/api/README.md) \ No newline at end of file