Skip to content

Latest commit

 

History

History
608 lines (474 loc) · 36.6 KB

api-documentation.md

File metadata and controls

608 lines (474 loc) · 36.6 KB
Raw

Gomoku API Documentation

The document describes the API.

Table of Contents

Home

Gets the home resource, mainly with the primary (direct connected) and global (indirect connected) navigation links and actions. See Navigation Graph.

Request

  • Method: GET
  • Path: /api/

Response

System

About

Gets the about resource, mainly with information about the current version of the system and information about the respective developers.

Request

  • Method: GET
  • Path: /api/system

Response

Users

Ranking

Gets the current paged ranking of users, mainly with information on the total number of users and the statistics of each one on that page. Furthermore, there is a related link to each individual's user statistics.

Request

  • Method: GET
  • Path: /api/users/ranking
  • [ Query ?page=__ ]

Response

Statistics

Gets a user's statistics, mainly the number of games played, won, lost and tied.

Request

  • Method: GET
  • Path: /api/users/{userId}/statistics

Response

SignUp (Create User)

Creates a user with necessary information.

Request

  • Method: POST
  • Path: /api/users
  • Headers:
  • Body: 
    {
    "username": text,
    "email": text,
    "password": text
}

Response

LogIn (Create Token)

Create a temporary token for access to resources that require authorization.

Request

  • Method: POST
  • Path: /api/users/token
  • Headers:
  • Body: 
    {
    "identity": text,
    "password": text
}

Response

GetUser

Gets a user's public information.

Request

  • Method: GET
  • Path: /api/users/{userId}

Response

Logout

Invalidate a temporary token created for access to resources that require authorization.

Request

Response

UserHome

Gets a user's personal information and the links and actions within the account.

Request

Response

Games

Variants

Gets information of all supported variants.

Request

Response

Variant

Gets information for one of the supported variants.

Request

  • Method: GET
  • Path: /api/games/variants/{variantId}
  • Headers:

Response

Start

Express a desire to start a game. There are two scenarios if it is successful. In the first scenario, the request was registered, i.e., as there is currently no other player waiting to play, the request is registered and it is possible to monitor the starting status of the game. In the second case the game was started, i.e., as there was a player waiting, the game could be started.

NOTE: The user who waited for the other user play with the black pieces (player b) and the user who joined the game will play with the white pieces (player w).

Request

{
    "variantId": Int
}

Response

StatusMonitor

Get the status of the game start monitor. There are two scenarios if it is successful, either the player continues waiting or someone has already joined.

Request

  • Method: GET
  • Path: /api/games/{gameId}/monitor
  • Headers:

Response

DeleteMonitor

Give up waiting for other player.

Request

  • Method: DELETE
  • Method: /api/games/{gameId}/monitor
  • Headers:

Response

GetGame

Get current game status.

Request

Response

Play

Apply a move to a game.

Request

  • Method: PUT
  • Path: /api/games/{gameId}/play/row/{row}/column/{column}
  • Headers:

Response

GiveUp

Quit a game.

NOTE: Quitting a game means another game played and a game lost in the statistics.

Request

  • Method: PUT
  • Path: /api/games/{gameId}/giveup
  • Headers:

Response

Media Types

application/vnd.siren+json

Media type for success responses according to Siren (Hypermedia).

Custom Link Relation Description
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/rel/about Refers to a resource that contains information about the system version and the author(s).
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/rel/ranking Refers to a resource that contains the paginated ranking of users.
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/rel/statistics Refers to a resource that contains a user's statistics.
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/rel/userHome Refers to a resource that contains a user's personal information.
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/rel/variants Refers to a resource that contains the information of all supported variants.
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/rel/game Refers to a resource that contains the information of a game.
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/rel/monitor Refers to a resource that contains the information of a game start status monitor.
Custom Action Description
signup Action to create a user.
login Action to create a temporary token to access resources that require authorization.
logout Action to inactivate a temporary token to access resources that require authorization.
start-game Action to express desire in starting a game.
cancel Action to cancel waiting for another user to start a game.
play Action to apply a move to a game.
give-up Action to quit a game.

NOTE: The remaining link relations used are described in IANA - Link Relations.

Example of a response with media type application/vnd.siren+json:

{
    "class": [
        "game"
    ],
    "properties": {
        "gameState": "NEXT_TURN_B",
        "playerB": 1,
        "playerW": 2,
        "playingRoundTime": "5m",
        "pieces": [],
        "variantId": 1
    },
    "links": [
        {
            "rel": [
                "self"
            ],
            "href": "/api/games/ff0d5e34-8c28-49dd-9c0e-6ceafbf9934b",
            "authenticationType": [
                "BEARER",
                "COOKIE"
            ]
        },
        {
            "rel": [
                "https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/rel/variant"
            ],
            "href": "/api/games/variants/1",
            "authenticationType": [
                "BEARER",
                "COOKIE"
            ]
        }
    ],
    "entities": [],
    "actions": [
        {
            "name": "play",
            "title": "Make a move",
            "href": "/api/games/{id}/play/row/{row}/column/{column}",
            "method": "PUT",
            "authenticationType": [
                "BEARER",
                "COOKIE"
            ],
            "fields": []
        },
        {
            "name": "give-up",
            "title": "Give up on game",
            "href": "/api/games/ff0d5e34-8c28-49dd-9c0e-6ceafbf9934b/giveup",
            "method": "PUT",
            "authenticationType": [
                "BEARER",
                "COOKIE"
            ],
            "fields": []
        }
    ]
}

application/json

Media type for body requests type according to RFC 4627.

application/problem+json

Media type for failure responses according to RFC 7807.

Custom Type Field Description
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/problem/userNotFound The requested user was not found.
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/problem/userAlreadyExists The user already exists.
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/problem/insecurePassword The chosen password is not secure.
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/problem/emailNotValid The chosen email does not have a valid format.
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/problem/invalidCredentials The credentials indicated are not valid.
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/problem/playerAlreadyWaiting The player is already waiting for another player to start a game.
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/problem/invalidVariant The requested variant are not valid.
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/problem/monitorNotFound The requested status monitor was not found.
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/problem/gameNotFound The requested game was not found.
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/problem/playerNotPartOfGame The player is not one of the players in the requested game.
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/problem/moveNotValid The requested move is not valid.
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/problem/gameAlreadyEnded The requested game has ended.
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/problem/notYourTurn It's not the player's turn to play.
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/problem/timeOut The time limit for making a move has been exceeded.
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/problem/invalidRequestContent The content of the request is not valid.
https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/problem/internalServerError Something went wrong. Please try again later.

Example of a response with media type application/problem+json:

{
    "type": "https://github.com/isel-leic-daw/2023-daw-leic51d-07/tree/main/docs/api/problem/gameNotFound",
    "title": "Game not found.",
    "detail": "Game with id 'ff0d5e34-8c28-49dd-9c0e-06ceafbf9934' not found."
}

Request Details

Path field Type Description
userId number User identifier.
gameId number Game identifier.
variantId number Variant identifier.
row number Board row where you want to play. The first position in the row is 0 and last is boardDim - 1 of the chosen game variant.
column number Board column where you want to play. The first position in the column is 0 and last is boardDim - 1 of the chosen game variant.
Query field Type Description
page number Optional intended page in paginated resources.
Body fields Type Description
username text Descriptive text about the desired username for the user. The field can not be empty and is required.
email text Descriptive text about the desired email for the user. The field must match a valid email format, i.e., it must have exactly one @ character and at least one . character. The field can not be empty and is required.
password text Descriptive text about the desired password for the user. The field must have security requirements, i.e., it must have at least 6 characters, at least one digit, at least one lowercase letter and at least one uppercase letter. The field can not be empty and is required.
identity text Descriptive text about user identification of a user. The field may correspond to the username or email indicated when creating the user. The field can not be empty and is required.
variantId number Descriptive number about the desired game variant. The field is optional.

Response Details

Class value Type Description
home text Home entity represents primary navigation links.
system-info text System-Info entity represents information about system, namely system version.
system-authors text System-Authors entity represents information about the developers of the current version of the API.
ranking text Ranking entity represents the current ranking of users' scores.
user text User entity represents the public information of a user.
statistics text Statistics entity represents the current statistics of requested user.
authorization text Authorization entity represents user authentication for authenticated resource access.
user-home text User Home entity represents the user's personal information and the links and actions within the account.
variant text Variant entity represents information of one supported variants.
variants text Variants entity represents information of all supported variants.
monitor text Monitor entity represents the state monitoring "object" while the game is not starting.
game text Game entity represents the game.
Property name Property value Type Description
welcome - text Welcome message.
version - text Current version of system, in Semantic-versioning scheme.
createdAt - text Current system version creation date.
authors - array Current system version authors.
firstName - text Author's first name.
surname - text Author's surname.
email - text Author's or User's email.
userId - number User identifier.
user-{userI}-statistics - text The related statistics for user .
username - text User username.
totalUsers - number The current total number of users. The value 0 represents that there is no user.
token - string Temporary token for access to resources that require authorization.
expiration - string Token expiration date and time.
rankingPosition - number Current position occupied in the ranking.
gamesPlayed - number Number of games played by the user. The value 0 represents that the player has not played any games yet.
gamesWon - number Number of games won by the user. The value 0 represents that the player has not won any games yet.
gamesLost - text Number of games lost by the user. The value 0 represents that the player has not lost any games yet.
gamesTied - text Number of games tied by the user. The value 0 represents that the player has not tied any games yet.
variants - array Current supported game variants. A variant is a set of boardDim, openingRules and playingRules.
variantId - number Variant identifier.
boardDim - number The size of game board is boardDim * boardDim.
openingRules 1 - NONE text 1 - There are no specific opening rules.
playingRules 1 - FREESTYLE text 1 - The standard game without specific gameplay rules.
status 1 - WAITING_FOR_OTHER_PLAYER
2 - OTHER_PLAYER_JOINED		 text 1 - Waiting state for another player to start the game.
2 - Terminal state given that another player has already joined and the game has started.
askAgainIn - text Recommended time (in seconds) to monitor the status once again or 'null' if no longer needed.
gameState 1 - NEXT_TURN_W
2 - NEXT_TURN_B
3 - WINNER_W
4 - WINNER_B
5 - DRAW		 text 1 - It's the white player's turn.
2 - It's the black player's turn.
3 - The game is over and the white player has won.
4 - The game is over and the black player has won.
5 - The game is over and tied.
playerB - text The identifier of the user who is playing with the black pieces in the current game.
playerW - text The identifier of the user who is playing with the white pieces in the current game.
playingRoundTime - text The time to play the round (in minutes).
pieces - array All the pieces present on the game board, where each piece corresponds to a player and an intersection.
player 1 - B
2 - W		 text 1 - Player with the black pieces
2 - Player with the white pieces.
intersection - object Intersection is the position corresponding to a row and a column.
row - number Board row. The first position in the row is 0 and last is boardDim - 1 of the chosen game variant.
column - number Board column. The first position in the column is 0 and last is boardDim - 1 of the chosen game variant.

Authorization

Field name Field value Description
authenticationType 1 - NONE
2 - BEARER
3 - COOKIE		 1 - The subsequent request does not require authentication to be performed.
2 - The subsequent request requires authentication to be executed, it requires the inclusion of the authentication header in the HTTP request with the bearer token.
3 - The subsequent request requires authentication to be executed, it requires the inclusion of the cookie header in the HTTP request with the token.

Navigation Graph

The following graph corresponds to the supported navigation graph.

NavigationGraph