479 lines
15 KiB
YAML
479 lines
15 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: Monster Trading Cards Game
|
|
description: |-
|
|
This is the specification of the required API endpoints for the MTCG server.
|
|
servers:
|
|
- url: http://localhost:10001
|
|
tags:
|
|
- name: users
|
|
description: User registration and login
|
|
- name: packages
|
|
description: Package creation and acquisition
|
|
- name: cards
|
|
description: Card and deck management
|
|
- name: game
|
|
description: Battle related endpoints
|
|
- name: trading
|
|
description: Card trading
|
|
paths:
|
|
/users:
|
|
post:
|
|
tags:
|
|
- users
|
|
summary: Register a new user
|
|
description: Register a new user with username and password
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#components/schemas/UserCredentials'
|
|
required: true
|
|
responses:
|
|
'201':
|
|
description: User successfully created
|
|
'409':
|
|
description: User with same username already registered
|
|
/users/{username}:
|
|
get:
|
|
tags:
|
|
- users
|
|
summary: Retrieves the user data for the given username.
|
|
description: Retrieves the user data for the username provided in the route. Only the admin or the matching user can successfully retrieve the data.
|
|
parameters:
|
|
- in: path
|
|
name: username
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: kienboec
|
|
description: The username from a user's credentials.
|
|
responses:
|
|
'200':
|
|
description: Data successfully retrieved
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UserData'
|
|
'401':
|
|
$ref: '#/components/responses/UnauthorizedError'
|
|
'404':
|
|
description: User not found.
|
|
security:
|
|
- mtcgAuth: []
|
|
put:
|
|
tags:
|
|
- users
|
|
summary: Updates the user data for the given username.
|
|
description: Retrieves the user data for the username provided in the route. Only the admin or the matching user can successfully retrieve the data.
|
|
parameters:
|
|
- in: path
|
|
name: username
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: kienboec
|
|
description: The username from a user's credentials.
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#components/schemas/UserData'
|
|
required: true
|
|
responses:
|
|
'200':
|
|
description: User sucessfully updated.
|
|
'401':
|
|
$ref: '#/components/responses/UnauthorizedError'
|
|
'404':
|
|
description: User not found.
|
|
security:
|
|
- mtcgAuth: []
|
|
/sessions:
|
|
post:
|
|
tags:
|
|
- users
|
|
summary: Login with existing user
|
|
description: Login a user with username and password
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#components/schemas/UserCredentials'
|
|
required: true
|
|
responses:
|
|
'200':
|
|
description: User login successful
|
|
'401':
|
|
description: Invalid username/password provided
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: string
|
|
description: The token for authenticated users.
|
|
example: kienboec-mtcgToken
|
|
/packages:
|
|
post:
|
|
tags:
|
|
- packages
|
|
summary: Create new card packages (requires admin)
|
|
description: Creates a new package from an array of cards. Only the "admin" user may do this
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Card'
|
|
minItems: 5
|
|
maxItems: 5
|
|
required: true
|
|
responses:
|
|
'201':
|
|
description: Package and cards successfully created
|
|
'401':
|
|
$ref: '#/components/responses/UnauthorizedError'
|
|
'403':
|
|
description: Provided user is not "admin"
|
|
'409':
|
|
description: At least one card in the packages already exists
|
|
security:
|
|
- mtcgAuth: []
|
|
/transactions/packages:
|
|
post:
|
|
tags:
|
|
- packages
|
|
summary: Acquire a card package
|
|
description: Buys a card package with the money of the provided user
|
|
responses:
|
|
'200':
|
|
description: A package has been successfully bought
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Card'
|
|
'401':
|
|
$ref: '#/components/responses/UnauthorizedError'
|
|
'403':
|
|
description: Not enough money for buying a card package
|
|
'404':
|
|
description: No card package available for buying
|
|
security:
|
|
- mtcgAuth: []
|
|
/cards:
|
|
get:
|
|
tags:
|
|
- cards
|
|
summary: Shows a user's cards
|
|
description: Returns all cards that have been required by the provided user
|
|
responses:
|
|
'200':
|
|
description: The user has cards, the response contains these
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Card'
|
|
'204':
|
|
description: The request was fine, but the user doesn't have any cards
|
|
'401':
|
|
$ref: '#/components/responses/UnauthorizedError'
|
|
security:
|
|
- mtcgAuth: []
|
|
/deck:
|
|
get:
|
|
tags:
|
|
- cards
|
|
summary: Shows the user's currently configured deck
|
|
description: Returns the cards that are owned by the uses and are put into the deck
|
|
parameters:
|
|
- in: query
|
|
name: format
|
|
required: false
|
|
schema:
|
|
type: string
|
|
enum: [plain, json]
|
|
default: json
|
|
description: The requested format of the response
|
|
responses:
|
|
'200':
|
|
description: The deck has cards, the response contains these
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Card'
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: The textual deck description.
|
|
'204':
|
|
description: The request was fine, but the deck doesn't have any cards
|
|
'401':
|
|
$ref: '#/components/responses/UnauthorizedError'
|
|
security:
|
|
- mtcgAuth: []
|
|
put:
|
|
tags:
|
|
- cards
|
|
summary: Configures the deck with four provided cards
|
|
description: Send four card IDs to configure a new full deck. A failed request will not change the previously defined deck.
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
format: uuid
|
|
minItems: 4
|
|
maxItems: 4
|
|
uniqueItems: true
|
|
required: true
|
|
responses:
|
|
'200':
|
|
description: The deck has been successfully configured
|
|
'400':
|
|
description: The provided deck did not include the required amount of cards
|
|
'401':
|
|
$ref: '#/components/responses/UnauthorizedError'
|
|
'403':
|
|
description: At least one of the provided cards does not belong to the user or is not available.
|
|
security:
|
|
- mtcgAuth: []
|
|
/stats:
|
|
get:
|
|
tags:
|
|
- game
|
|
summary: Retrieves the stats for an individual user
|
|
description: Retrieves the stats for the requesting user.
|
|
responses:
|
|
'200':
|
|
description: The stats could be retrieved successfully.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UserStats'
|
|
'401':
|
|
$ref: '#/components/responses/UnauthorizedError'
|
|
security:
|
|
- mtcgAuth: []
|
|
/scoreboard:
|
|
get:
|
|
tags:
|
|
- game
|
|
summary: Retrieves the user scoreboard ordered by the user's ELO.
|
|
responses:
|
|
'200':
|
|
description: The scoreboard could be retrieved successfully.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/UserStats'
|
|
'401':
|
|
$ref: '#/components/responses/UnauthorizedError'
|
|
security:
|
|
- mtcgAuth: []
|
|
/battles:
|
|
post:
|
|
tags:
|
|
- game
|
|
summary: Enters the lobby to start a battle.
|
|
description: If there is already another user in the lobby, the battle will start immediately. Otherwise the request will wait for another user to enter.
|
|
responses:
|
|
'200':
|
|
description: The battle has been carried out successfully.
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: The battle log.
|
|
'401':
|
|
$ref: '#/components/responses/UnauthorizedError'
|
|
/tradings:
|
|
get:
|
|
tags:
|
|
- trading
|
|
summary: Retrieves the currently available trading deals.
|
|
responses:
|
|
'200':
|
|
description: There are trading deals available, the response contains these
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/TradingDeal'
|
|
'204':
|
|
description: The request was fine, but there are no trading deals available
|
|
'401':
|
|
$ref: '#/components/responses/UnauthorizedError'
|
|
security:
|
|
- mtcgAuth: []
|
|
post:
|
|
tags:
|
|
- trading
|
|
summary: Creates a new trading deal.
|
|
description: Creates a new trading deal. You can only create a deal for a card you own.
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TradingDeal'
|
|
required: true
|
|
responses:
|
|
'201':
|
|
description: Trading deal successfully created
|
|
'401':
|
|
$ref: '#/components/responses/UnauthorizedError'
|
|
'403':
|
|
description: The deal contains a card that is not owned by the user or locked in the deck.
|
|
'409':
|
|
description: A deal with this deal ID already exists.
|
|
security:
|
|
- mtcgAuth: []
|
|
/tradings/{tradingdealid}:
|
|
delete:
|
|
tags:
|
|
- trading
|
|
summary: Deletes an existing trading deal.
|
|
description: Deletes an existing trading deal. It is only allowed if the user owns the associated card.
|
|
parameters:
|
|
- in: path
|
|
name: tradingdealid
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
description: The ID of the trading deal to delete.
|
|
responses:
|
|
'200':
|
|
description: Trading deal successfully deleted
|
|
'401':
|
|
$ref: '#/components/responses/UnauthorizedError'
|
|
'403':
|
|
description: The deal contains a card that is not owned by the user.
|
|
'404':
|
|
description: The provided deal ID was not found.
|
|
'409':
|
|
description: A deal with this deal ID already exists.
|
|
security:
|
|
- mtcgAuth: []
|
|
post:
|
|
tags:
|
|
- trading
|
|
summary: Carry out a trade for the deal with the provided card.
|
|
description: Carry out a trade for the deal with the provided card. Trading with self is not allowed.
|
|
parameters:
|
|
- in: path
|
|
name: tradingdealid
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
description: The ID of the trading deal to carry out.
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
description: The ID of the offered card.
|
|
responses:
|
|
'200':
|
|
description: Trading deal successfully executed.
|
|
'401':
|
|
$ref: '#/components/responses/UnauthorizedError'
|
|
'403':
|
|
description: The offered card is not owned by the user, or the requirements are not met (Type, MinimumDamage), or the offered card is locked in the deck.
|
|
'404':
|
|
description: The provided deal ID was not found.
|
|
security:
|
|
- mtcgAuth: []
|
|
|
|
components:
|
|
schemas:
|
|
UserCredentials:
|
|
type: object
|
|
properties:
|
|
Username:
|
|
type: string
|
|
example: kienboec
|
|
Password:
|
|
type: string
|
|
example: daniel
|
|
UserData:
|
|
type: object
|
|
properties:
|
|
Name:
|
|
type: string
|
|
example: Hoax
|
|
Bio:
|
|
type: string
|
|
example: me playin...
|
|
Image:
|
|
type: string
|
|
example: :-)
|
|
UserStats:
|
|
type: object
|
|
properties:
|
|
Name:
|
|
type: string
|
|
example: Hoax
|
|
description: The name of the user (from the user data).
|
|
Elo:
|
|
type: integer
|
|
Wins:
|
|
type: integer
|
|
Losses:
|
|
type: integer
|
|
Card:
|
|
type: object
|
|
properties:
|
|
Id:
|
|
type: string
|
|
format: uuid
|
|
Name:
|
|
type: string
|
|
enum: [WaterGoblin, FireGoblin, RegularGoblin, WaterTroll, FireTroll, RegularTroll, WaterElf, FireElf, RegularElf, WaterSpell, FireSpell, RegularSpell, Knight, Dragon, Ork, Kraken]
|
|
example: WaterGoblin
|
|
Damage:
|
|
type: number
|
|
format: float
|
|
example: 55.0
|
|
TradingDeal:
|
|
type: object
|
|
properties:
|
|
Id:
|
|
type: string
|
|
format: uuid
|
|
description: The ID of the deal
|
|
CardToTrade:
|
|
type: string
|
|
format: uuid
|
|
description: The card ID offered
|
|
Type:
|
|
type: string
|
|
enum: [monster, spell]
|
|
example: monster
|
|
description: The required card type of the received card
|
|
MinimumDamage:
|
|
type: number
|
|
format: float
|
|
example: 15
|
|
description: The required minimum damage of the the received card
|
|
|
|
securitySchemes:
|
|
mtcgAuth:
|
|
type: http
|
|
scheme: bearer
|
|
responses:
|
|
UnauthorizedError:
|
|
description: Access token is missing or invalid
|