Skip to content

Latest commit

 

History

History
1368 lines (863 loc) · 38.4 KB

documentation.md

File metadata and controls

1368 lines (863 loc) · 38.4 KB
Raw

CHESS PLUGIN DOCUMENTATIONS OVERVIEW

Zuri chess plugin is a web based recreational and competitive board game played between two players with an option for AI, that can easily be installed and used as part of the Zuri chat main application.

TABLE OF CONTENT: Quick reference

Get Started

Our API is organized around using HTTP verbs and REST. This API accepts and returns JSON formatted payload

Authorization

User must be authenticated to use the API

HEADERS
Authorization "Bearer {token}"

Plugin Information

When this endpoint is used, it Returns all the information for this chess application plugin.

How To Use

This is a GET endpoint and it simple means that your browser e.g chrome, edge, etc can make request (i.e write/send the endpoint in their browser engine) and see the response (i.e the plugin information).

Input the endpoint in the browser and hit enter, when successful, onSuccess response is display as JSON formatted in the browser. when an error occur onError is thrown.

Features

This involves the baseUrl, body request type, all required and non required parameters, methods and url for this endpoint.

URL METHOD URL PARAMS DATA PARAMS
/info GET false false

Responses

This is the end result send back to the client on successful execution or when an error occur. Below are the response on this two scenarios

onSuccess

This return a json formatted response payload to the client browser display in addition to the code.

  • code :

    • 2xx -> This success ranges originate from the server, usually from a successful request(200). etc

  • payload :

    • result
  {
    plugin_id: "61448b7c976307hjc83Cdh5",
    name: "Chess Plugin",
    description:
      "Ease stress in Zuri's chess room while running business deals, socialize with friends and colleagues by engaging in a friendly chess match. You could also decide to spectate a chess game and make comments while you watch.",
    category: "Games",
    pictures: [
      "https://res.cloudinary.com/kyloren/image/upload/v1631878728/Chess%20MarketPlace/intro_gk0icz.png",
      ],
    icon_url:
      "https://images.unsplash.com/photo-1529699211952-734e80c4d42b?",
    scaffold_structure: "Single SPA",
    version: "v1.0",
    developer_name: "HNG 8.0/Team Tesla",
    developer_email: "hello@zuri.com",
    sidebar_url: "https://chess.zuri.chat/api/v1/sideBar",
    ping_url: "https://chess.zuri.chat/api/v1/ping",
    homepage_url: "https://chess.zuri.chat/",
    install_url: "https://chess.zuri.chat/",
  }
]
  • message : "Plugin Information Retrieved"

onError

  • code :

    • 4xx -> This error ranges originate from the client, possible from a bad request(403),page not found (404), unauthorized access(402). etc

    • 5xx -> This error ranges originate from the server, possible the server being down(500). etc

  • payload :

    • error
  Error object
  • message : "Could not fetch plugin information"

Sidebar Information

When this endpoint is used, it Returns all the information for this chess application sidebar.

How To Use

This is a GET endpoint and it simple means that your browser e.g chrome, edge, etc can make request (i.e write/send the endpoint in their browser engine) and see the response (i.e the plugin information).

Input/insert the endpoint complete url in the browser and hit enter, when successful, onSuccess response is display as JSON formatted in the browser. when an error occur onError is thrown.

Features

This involves the baseUrl, body request type, all required and non required parameters, methods and url for this endpoint.

URL METHOD URL PARAMS DATA PARAMS
/sidebar GET True False
  • URL PARAMS if True
    • The URL parameter is passed in the endpoint as a query parameter
NAME DATA TYPE REQUIRED
user string true
org string true

Responses

This is the end result send back to the client on successful execution or when an error occur. Below are the response on this two scenarios

onSuccess

This return a json formatted response payload to the client browser display in addition to the code.

  • code :

    • 2xx -> This success ranges originate from the server, usually from a successful request(200). etc

  • payload :

    • result
 name: "Chess Plugin",
        description: "The Chess plugin",
        plugin_id: PLUGIN_ID,
        organisation_id: org,
        user_id: user,
        group_name: "Chess Games",
        show_group: true,
        public_rooms: [
          {
            room_name: "Chess room",
            room_image: "https://www.svgrepo.com/show/12072/chess-board.svg",
            room_url: "https://zuri.chat/chess",
          },
        ],
        joined_rooms,
]
  • message : "Fetch sidebar data"

onError

  • code :

    • 4xx -> This error ranges originate from the client, possible from a bad request(403),page not found (404), unauthorized access(402). etc

    • 5xx -> This error ranges originate from the server, possible the server being down(500). etc

  • payload :

    • error
  Error object
  • message : "Could not fetch sidebar information"

Create Game

When this endpoint is used, it Creates a new gaming room, assigns an Id to it and sets the status to started (state = 0).

How To Use

This is a POST endpoint and it can be tested with a form or through POSTMAN. There can not be more than 6 games running concurrently.

Once request is sent to the api endpoint with all neccesary parameters through a FORM or POSTMAN and hit enter. when successful, onSuccess response is return and game created. when an error occur onError is thrown.

  • Guidance Example on the https://zuri.chat/chess application :
    • Once you click on join as player 1, all parameters will be added automatically and on Success, you enter into the game created waiting for opponent

Features

This involves the baseUrl, body request type, all required and non required parameters, methods and url for this endpoint.

URL METHOD URL PARAMS DATA PARAMS
/game/create POST false true
  • PARAMS [URL OR DATA] if true
NAME DATA TYPE REQUIRED
user_id integer true
user_name string true
image_url string false

Responses

This is the end result send back to the client on successful execution or when an error occur. Below are the response on this two scenarios

onSuccess

This return a json formatted response payload to the client browser display in addition to the code.

  • code :

    • 2xx -> This success ranges originate from the server, usually from a successful request(200). etc

  • payload :

    • result
  { object_id: game._id }
]
  • message : "New Game Board Created successfully",

onError

  • code :

    • 4xx -> This error ranges originate from the client, possible from a bad request(403),page not found (404), unauthorized access(402). etc

    • 5xx -> This error ranges originate from the server, possible the server being down(500). etc

  • payload :

    • error
Error object
  • message_1 : "Unable to create a Game"
  • message_2 : "No free boards right now"

Join Game

When this endpoint is used, its check if an opponent already exist, if not it join as the opponent.

How To Use

This is a POST endpoint and it Enters a game as the second player. This can be tested from the client side in a form or using Postman.

Input the endpoint complete url into postman or form with all necessary parameter , when successful, onSuccess response is display as JSON formatted in the browser. when an error occur onError is thrown.

  • Guidance Example on the https://zuri.chat/chess application :
    • Once the link is open, user choose any six available game in the homepage to play as opponent. On clicked "join as opponent/player 2", the user enters the game and can start playing with the host.

Features

This involves the baseUrl, body request type, all required and non required parameters, methods and url for this endpoint.

URL METHOD URL PARAMS DATA PARAMS
/join POST false true
  • PARAMS [URL OR DATA] if true
NAME DATA TYPE REQUIRED
game_id string true
user_id integer true
user_name string true
image_url string false

Responses

This is the end result send back to the client on successful execution or when an error occur. Below are the response on this two scenarios

onSuccess

This return a json formatted response payload to the client browser display in addition to the code.

  • code :

    • 2xx -> This success ranges originate from the server, usually from a successful request(200). etc

  • payload :

    • result
game_id
  • message : "Game join successfully"

onError

  • code :

    • 4xx -> This error ranges originate from the client, possible from a bad request(403),page not found (404), unauthorized access(402). etc

    • 5xx -> This error ranges originate from the server, possible the server being down(500). etc

  • payload :

    • error
Error object
  • message_1 : "Unable to join a game"
  • message_2: "opponent already exists"
  • message_3: "Game not found"

All Game

When this endpoint is used, it returns all the game objects in the database of this chess application plugin.

How To Use

This is a GET endpoint and it simple means that your browser e.g chrome, edge, etc can make request (i.e write/send the endpoint in their browser engine) and see the response (i.e the plugin information).

Input the endpoint in the browser and hit enter, when successful, onSuccess response is display as JSON formatted in the browser. when an error occur onError is thrown.

  • Guidance Example on the https://zuri.chat/chess application:
    • Once the link is open, user see all games in the game box

Features

This involves the baseUrl, body request type, all required and non required parameters, methods and url for this endpoint.

URL METHOD URL PARAMS DATA PARAMS
/game/all GET false false

Responses

This is the end result send back to the client on successful execution or when an error occur. Below are the response on this two scenarios

onSuccess

This return a json formatted response payload to the client browser display in addition to the code.

  • code :

    • 2xx -> This success ranges originate from the server, usually from a successful request(200). etc

  • payload :

    • result
gameData
  • message : "Game retrieve successfully"

onError

  • code :

    • 4xx -> This error ranges originate from the client, possible from a bad request(403),page not found (404), unauthorized access(402). etc

    • 5xx -> This error ranges originate from the server, possible the server being down(500). etc

  • payload :

    • error
Error object
  • message : "Unable to get all Games"

Watch Game

When this endpoint is used, it allows a user to watch existing game play.

How To Use

This is a PATCH Method and it Enters a game as spectator.

This can be tested from the client side by calling the api or using Postman.

When successful, onSuccess response is display as JSON formatted in the browser. when an error occur onError is thrown.

  • Guidance Example on the https://zuri.chat/chess application :
    • Once the link is clicked,join as a spectator can and get the right to view and comments on the ongoing game.

Features

This involves the baseUrl, body request type, all required and non required parameters, methods and url for this endpoint.

URL METHOD URL PARAMS DATA PARAMS
/watch PATCH false true
  • PARAMS [URL OR DATA] if true
NAME DATA TYPE REQUIRED
game_id string true
user_id string true
user_name string true

Responses

This is the end result send back to the client on successful execution or when an error occur. Below are the response on this two scenarios

onSuccess

This return a json formatted response payload to the client browser display in addition to the code.

  • code :

    • 2xx -> This success ranges originate from the server, usually from a successful request(200). etc

  • payload :

    • result
  {
    payload
  }
  • message : "Joined as spectator successfully"

onError

  • code :

    • 4xx -> This error ranges originate from the client, possible from a bad request(403),page not found (404), unauthorized access(402). etc

    • 5xx -> This error ranges originate from the server, possible the server being down(500). etc

  • payload :

    • error
Error object
  • message_1 : "Unable to add spectator successfully"
  • message_2 : "Game not found"

Move Piece

When this endpoint is used, it Returns all the information for a chess piece moved. This endpoint sends out a single piecemove so that the other player and spectators can view it

How To Use

This is a PATCH endpoint.

This can be tested from the client side by calling the api or using Postman.

onSuccess response is display as JSON formatted in the browser. when an error occur onError is thrown.

  • Guidance Example on the https://zuri.chat/chess application :
    • Once the link is clicked, a user can enter the game as either player or player 2 and get to move game piece based of the game rules

Features

This involves the baseUrl, body request type, all required and non required parameters, methods and url for this endpoint.

URL METHOD URL PARAMS DATA PARAMS
/piecemove PATCH false true
  • PARAMS [URL OR DATA] if true
NAME DATA TYPE REQUIRED
position_fen string true
user_id string true
game_id string true
board_state string true

Responses

This is the end result send back to the client on successful execution or when an error occur. Below are the response on this two scenarios

onSuccess

This return a json formatted response payload to the client browser display in addition to the code.

  • code :

    • 2xx -> This success ranges originate from the server, usually from a successful request(200). etc

  • payload :

    • result
{
  payload
}
  • message : "piece moved"

onError

  • code :

    • 4xx -> This error ranges originate from the client, possible from a bad request(403),page not found (404), unauthorized access(402). etc

    • 5xx -> This error ranges originate from the server, possible the server being down(500). etc

  • payload :

    • error
Error object
  • message_1 : "Failed to move piece"
  • message_2 : "Game not found"

End Game

Ends a game based on win. This endpoint is for ending a game that has a winner (not for draw)

How To Used

This is a PATCH endpoint.

This can be tested from the client side by calling the api or using Postman.

onSuccess response is display as JSON formatted in the browser. when an error occur onError is thrown.

  • Guidance Example on the https://zuri.chat/chess application :
  • Once the link is clicked, a user can click the forfeit button to end an ongoing game.

Features

This involves the baseUrl, body request type, all required and non required parameters, methods and url for this endpoint.

URL METHOD URL PARAMS DATA PARAMS
/end PATCH None True
  • DATA PARAMS if required
NAME DATA TYPE REQUIRED
game_id string true
user_id string true

Responses

This is the end result send back to the client on successful execution or when an error occur. Below are the response on this two scenarios

onSuccess

This return a json formatted response payload to the client browser display in addition to the code.

  • code :

    • 2xx -> This success ranges originate from the server, usually from a successful request(200). etc

  • payload :

    • result
  {
    payload
  }
  • message : "Game ended!!!"

onError

  • code :

    • 4xx -> This error ranges originate from the client, possible from a bad request(403),page not found (404), unauthorized access(402). etc

    • 5xx -> This error ranges originate from the server, possible the server being down(500). etc

  • payload :

    • error
<Error object>
  • message_1 : "User do not exist"
  • message_2 : "Game do not exist"

Unwatch Game

When this endpoint is used, it Removes a spectator from a game Room

How To Used

This is a PATCH endpoint.

This can be tested from the client side by calling the api or using Postman.

onSuccess response is display as JSON formatted in the browser. when an error occur onError is thrown.

  • Guidance Example on the https://zuri.chat/chess application :
    • Once the link is clicked, the spectator can unwatch and leave the ongoing game by clicking the leave button

Features

This involves the baseUrl, body request type, all required and non required parameters, methods and url for this endpoint.

URL METHOD URL PARAMS DATA PARAMS
/unwatch PATCH None True
  • DATA PARAMS if required
NAME DATA TYPE REQUIRED
game_id string true
user_id string true

Responses

This is the end result send back to the client on successful execution or when an error occur. Below are the response on this two scenarios

onSuccess

This return a json formatted response payload to the client browser display in addition to the code.

  • code :

    • 2xx -> This success ranges originate from the server, usually from a successful request(200). etc

  • payload :

    • result
  <payload >
  • message : "Game ended!!!"

onError

  • code :

    • 4xx -> This error ranges originate from the client, possible from a bad request(403),page not found (404), unauthorized access(402). etc

    • 5xx -> This error ranges originate from the server, possible the server being down(500). etc

  • payload :

    • error
<Error object>
  • message_1 : "User do not exist"
  • message_2 : "Game do not exist"

Resign Game

End game by forfeiting an ongoing game. This basically end game and choose the winner based on the user who forfeit the game against user that did not forfeit the game

How To Used

This is a PATCH endpoint.

This can be tested from the client side by calling the api or using Postman.

onSuccess response is display as JSON formatted in the browser. when an error occur onError is thrown.

Features

This involves the baseUrl, body request type, all required and non required parameters, methods and url for this endpoint.

URL METHOD URL PARAMS DATA PARAMS
/resign Patch false true
  • PARAMS [URL OR DATA] if true
NAME DATA TYPE REQUIRED
game_id string true
user_id string true

Responses

This is the end result send back to the client on successful execution or when an error occur. Below are the response on this two scenarios

onSuccess

This return a json formatted response payload to the client browser display in addition to the code.

  • code :

    • 2xx -> This success ranges originate from the server, usually from a successful request(200). etc

  • payload :

    • result
  <payload>
  • message : "successful"

onError

  • code :

    • 4xx -> This error ranges originate from the client, possible from a bad request(403),page not found (404), unauthorized access(402). etc

    • 5xx -> This error ranges originate from the server, possible the server being down(500). etc

  • payload :

    • error

Error object
  • message : "Could not fetch plugin information"

Game by id

When this endpoint is used, it returns a particular game using it's Id

How To Use

This is a GET endpoint and it simple means that your browser e.g chrome, edge, etc can make request (i.e write/send the endpoint in their browser engine) and see the response (i.e the plugin information). You can also use Postman or other API testing platform to make request to the endpoint.

Input the endpoint in the browser, or any API testing platform and hit enter, when successful, onSuccess response is display as JSON formatted in the browser ( or the API testing platform). when an error occur onError is thrown.

Features

This involves the baseUrl, body request type, all required and non required parameters, methods and url for this endpoint.

URL METHOD URL PARAMS DATA PARAMS
/game GET true false
  • PARAMS [URL OR DATA] if true
NAME DATA TYPE REQUIRED
game_id string true

Responses

This is the end result send back to the client on successful execution or when an error occur. Below are the response on this two scenarios

onSuccess

This return a json formatted response payload to the client browser display in addition to the code.

  • code :

    • 2xx -> This success ranges originate from the server, usually from a successful request(200). etc

  • payload :

    • result
  • message : "Game retrieved successfully"

onError

  • code :

    • 4xx -> This error ranges originate from the client, possible from a bad request(403),page not found (404), unauthorized access(402). etc

    • 5xx -> This error ranges originate from the server, possible the server being down(500). etc

  • payload :

    • error
Error object
  • message : "Game not found"

Game by user id

When this endpoint is used, it retrieves a game base on user Id being provided.

How To Use

This is a GET endpoint and it simple means that your browser e.g chrome, edge, etc can make request (i.e write/send the endpoint in their browser engine) and see the response (i.e the plugin information). You can also use Postman or other API testing platform to make request to the endpoint.

Input the endpoint in the browser, or any API testing platform and hit enter, when successful, onSuccess response is display as JSON formatted in the browser ( or the API testing platform). when an error occur onError is thrown.

Features

This involves the baseUrl, body request type, all required and non required parameters, methods and url for this endpoint.

URL METHOD URL PARAMS DATA PARAMS
/game GET true false
  • PARAMS [URL OR DATA] if true
NAME DATA TYPE REQUIRED
user_Id string true

Responses

This is the end result send back to the client on successful execution or when an error occur. Below are the response on this two scenarios

onSuccess

This return a json formatted response payload to the client browser display in addition to the code.

  • code :

    • 2xx -> This success ranges originate from the server, usually from a successful request(200). etc

  • payload :

    • result
{
  payload
}
  • message : "Game retrieved successfully"

onError

  • code :

    • 4xx -> This error ranges originate from the client, possible from a bad request(403),page not found (404), unauthorized access(402). etc

    • 5xx -> This error ranges originate from the server, possible the server being down(500). etc

  • payload :

    • error
  <Error object/>

  • message : "Game not found"

Game Comments

When this endpoint is used, it updates the comments being made by the spectators .

How To Use

This is a PATCH endpoint and it simple means that your browser e.g chrome, edge, etc can make request (i.e write/send the endpoint in their browser engine) and see the response (i.e the plugin information). You can also use Postman or other API testing platform to make request to the endpoint.

Input the endpoint in the browser, or any API testing platform and hit enter, when successful, onSuccess response is display as JSON formatted in the browser ( or the API testing platform). when an error occur onError is thrown.

Features

This involves the baseUrl, body request type, all required and non required parameters, methods and url for this endpoint.

URL METHOD URL PARAMS DATA PARAMS
/comment PATCH false true
  • PARAMS [URL OR DATA] if true
NAME DATA TYPE REQUIRED
user_name string true
image_url string true
text string true
timestamp string true

Responses

This is the end result send back to the client on successful execution or when an error occur. Below are the response on this two scenarios

onSuccess

This return a json formatted response payload to the client browser display in addition to the code.

  • code :

    • 2xx -> This success ranges originate from the server, usually from a successful request(200). etc

  • payload :

    • result
{
  payload
}
  • message : "Comment Sent"

onError

  • code :

    • 4xx -> This error ranges originate from the client, possible from a bad request(403),page not found (404), unauthorized access(402). etc

    • 5xx -> This error ranges originate from the server, possible the server being down(500). etc

  • payload :

    • error
<Error Object/>

  • message : "Comment cannot be empty"

Game delete

When this endpoint is used, it deletes a particular game from the database .

How To Use

This is a DELETE endpoint and it simple means that your browser e.g chrome, edge, etc can make request (i.e write/send the endpoint in their browser engine) and see the response (i.e the plugin information). You can also use Postman or other API testing platform to make request to the endpoint.

Input the endpoint in the browser, or any API testing platform and hit enter, when successful, onSuccess response is display as JSON formatted in the browser ( or the API testing platform). when an error occur onError is thrown.

Features

This involves the baseUrl, body request type, all required and non required parameters, methods and url for this endpoint.

URL METHOD URL PARAMS DATA PARAMS
/delete DELETE false true
  • PARAMS[URL OR DATA] if true
NAME DATA TYPE REQUIRED
game_id string true

Responses

This is the end result send back to the client on successful execution or when an error occur. Below are the response on this two scenarios

onSuccess

This return a json formatted response payload to the client browser display in addition to the code.

  • code :

    • 2xx -> This success ranges originate from the server, usually from a successful request(200). etc

  • payload :

    • result
{
  payload
}
  • message : "game deleted successfully"

onError

  • code :

    • 4xx -> This error ranges originate from the client, possible from a bad request(403),page not found (404), unauthorized access(402). etc

    • 5xx -> This error ranges originate from the server, possible the server being down(500). etc

  • payload :

    • error
<Error object/>

  • message : "Unable to delete game"

All Results

When this endpoint is used, it returns results of all games from the database .

How To Used

This is a GET endpoint and it simple means that your browser e.g chrome, edge, etc can make request (i.e write/send the endpoint in their browser engine) and see the response (i.e the plugin information). You can also use Postman or other API testing platform to make request to the endpoint.

Input the endpoint in the browser, or any API testing platform and hit enter, when successful, onSuccess response is display as JSON formatted in the browser ( or the API testing platform). when an error occur onError is thrown.

Features

This involves the baseUrl, body request type, all required and non required parameters, methods and url for this endpoint.

URL METHOD URL PARAMS DATA PARAMS
/result/all GET false false
  • PARAMS [URL OR DATA] if true
NAME DATA TYPE REQUIRED

Responses

This is the end result send back to the client on successful execution or when an error occur. Below are the response on this two scenarios

onSuccess

This return a json formatted response payload to the client browser display in addition to the code.

  • code :

    • 2xx -> This success ranges originate from the server, usually from a successful request(200). etc

  • payload :

    • result
{
  payload
}
  • message : "Results retrieved successfully"

onError

  • code :

    • 4xx -> This error ranges originate from the client, possible from a bad request(403),page not found (404), unauthorized access(402). etc

    • 5xx -> This error ranges originate from the server, possible the server being down(500). etc

  • payload :

    • error
<Error object/>

  • message : "Unable to get all Results"

Results by game id

When this endpoint is used, it returns result of particular game from the database base on it's Id .

How To Use

This is a GET endpoint and it simple means that your browser e.g chrome, edge, etc can make request (i.e write/send the endpoint in their browser engine) and see the response (i.e the plugin information). You can also use Postman or other API testing platform to make request to the endpoint.

Input the endpoint in the browser, or any API testing platform and hit enter, when successful, onSuccess response is display as JSON formatted in the browser ( or the API testing platform). when an error occur onError is thrown.

Features

This involves the baseUrl, body request type, all required and non required parameters, methods and url for this endpoint.

URL METHOD URL PARAMS DATA PARAMS
/result GET true false
  • PARAMS [URL OR DATA] if true
NAME DATA TYPE REQUIRED
game_id string true

Responses

This is the end result send back to the client on successful execution or when an error occur. Below are the response on this two scenarios

onSuccess

This return a json formatted response payload to the client browser display in addition to the code.

  • code :

    • 2xx -> This success ranges originate from the server, usually from a successful request(200). etc

  • payload :

    • result
[
payload
]
  • message : "Result retrieved successfully"

onError

  • code :

    • 4xx -> This error ranges originate from the client, possible from a bad request(403),page not found (404), unauthorized access(402). etc

    • 5xx -> This error ranges originate from the server, possible the server being down(500). etc

  • payload :

    • error
 < Error object/>
  • message : "Unable to get Result"