API Documentation - peter-monahan/Just-Chess GitHub Wiki

All endpoints that require authentication

All endpoints that require a current user to be logged in.

Request: endpoints that require authentication
Error Response: Require authentication
- Status Code: 401
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "message": "Authentication required",
  "statusCode": 401
}
```

All endpoints that require proper authorization

All endpoints that require authentication and the current user does not have the correct role(s) or permission(s).

Request: endpoints that require proper authorization
Error Response: Require proper authorization
- Status Code: 403
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "message": "Forbidden",
  "statusCode": 403
}
```

Get the Current User

Returns the information about the current user that is logged in.

Require Authentication: true
Request
- Method: GET
- URL: /session
- Body: none
Successful Response
- Status Code: 200
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "id": 1,
  "email": "[email protected]",
  "username": "JohnSmith"
}
```

Log In a User

Logs in a current user with valid credentials and returns the current user's information.

Require Authentication: false
Request
- Method: POST
- URL: /session
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "email": "[email protected]",
  "password": "secret password"
}
```
Successful Response
- Status Code: 200
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "id": 1,
  "email": "[email protected]",
  "username": "JohnSmith",
}
```
Error Response: Invalid credentials
- Status Code: 401
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "message": "Invalid credentials",
  "statusCode": 401
}
```

Error response: Body validation errors

Status Code: 400
Headers:
- Content-Type: application/json

Body:

{
  "message": "Validation error",
  "statusCode": 400,
  "errors": {
    "email": "Email is required",
    "password": "Password is required"
  }
}

Sign Up a User

Creates a new user, logs them in as the current user, and returns the current user's information.

Require Authentication: false

Request

Method: POST
URL: /users
Headers:
- Content-Type: application/json

Body:

{
  "username": "JohnSmith",
  "email": "[email protected]",
  "password": "secret password"
}

Successful Response
- Status Code: 200
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "id": 1,
  "username": "JohnSmith",
  "email": "[email protected]",
}
```

Error response: User already exists with the specified email

Status Code: 403
Headers:
- Content-Type: application/json

Body:

{
  "message": "User already exists",
  "statusCode": 403,
  "errors": {
    "email": "User with that email already exists"
  }
}

Error response: User already exists with the specified username

Status Code: 403
Headers:
- Content-Type: application/json

Body:

{
  "message": "User already exists",
  "statusCode": 403,
  "errors": {
    "username": "User with that username already exists"
  }
}

Error response: Body validation errors

Status Code: 400
Headers:
- Content-Type: application/json

Body:

{
  "message": "Validation error",
  "statusCode": 400,
  "errors": {
    "email": "Invalid email",
    "username": "Username is required",
  }
}

Games

Get all of a users current games

Returns all the games.

Require Authentication: true
Request
- Method: GET
- URL: /games
- Body: none

Successful Response

Status Code: 200
Headers:
- Content-Type: application/json

Body:

{
  "Games":[
    {
      "id": 1,
      "white_id": 1,
      "black_id": 2,
      "data": {"game data"},
      "createdAt": "2021-11-19 20:39:36",
      "updatedAt": "2021-11-19 20:39:36",
    }
  ]
}

Get a single game

Returns a game.

Require Authentication: true
Request
- Method: GET
- URL: /games/:game_id
- Body: none

Successful Response

Status Code: 200
Headers:
- Content-Type: application/json

Body:

   {
      "id": 1,
      "white_id": 1,
      "black_id": 2,
      "data": {"game data"},
      "createdAt": "2021-11-19 20:39:36",
      "updatedAt": "2021-11-19 20:39:36",
    }

Error response: Couldn't find a Game with the specified id
- Status Code: 404
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "message": "Game couldn't be found",
  "statusCode": 404
}
```

Create a Game request

Creates a new game

Require Authentication: true
Request
- Method: POST
- URL: /games
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "opponent_id": "1 or null if a random opponent is desired"
}
```

Successful Response

Status Code: 201
Headers:
- Content-Type: application/json

Body:

{
  "id": 1,
  "white_id": 1,
  "black_id": 2,
  "data": {"game data"},
  "createdAt": "2021-11-19 20:39:36",
  "updatedAt": "2021-11-19 20:39:36",
}

Error response: Couldn't find an opponent with the specified id
- Status Code: 404
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "message": "User couldn't be found",
  "statusCode": 404
}
```

Edit a Game

Edits and Updates an existing game.

Require Authentication: true
Request
- Method: PUT
- URL: /games/:game_id
- Headers:
  - Content-Type: application/json?
- Body:
```
{
  "type": "move",
  "data": "{'new game data'}",
}
```
Successful Response
- Status Code: 200
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "type": "move",
  "data": {"new game data"},
}
```

Forfeit a Game

Ends and deletes the game while giving your opponent the win.

Require Authentication: true
Require proper authorization: Game must belong to the current user
Request
- Method: DELETE
- URL: /games/:game_id
- Body: none
Successful Response
- Status Code: 200
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "message": "Successfully deleted",
  "statusCode": 200
}
```
Error response: Couldn't find a Game with the specified id
- Status Code: 404
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "message": "Game couldn't be found",
  "statusCode": 404
}
```

Messages

Get Message history with a specific user

Require Authentication: true
Request
- Method: GET
- URL: /messages/:user_id
- Body: none

Successful Response

Status Code: 200
Headers:
- Content-Type: application/json

Body:

{
  "Messages": [
    {
      "id": 1,
      "sender_id": 1,
      "receiver_id": 2,
      "content": "Words words words",
      "created_at": "2021-11-19 20:39:36",
      "updated_at": "2021-11-19 20:39:36"
    }
  ]
}

Send a Message to another user

Require Authentication: true
Request
- Method: POST
- URL: /messages
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "receiver_id": 1,
  "content": "Words words words"
}
```

Successful Response

Status Code: 201
Headers:
- Content-Type: application/json

Body:

{
  "id": 1,
  "sender_id": 1,
  "receiver_id": 2,
  "content": "Words words words",
  "createdAt": "2021-11-19 20:39:36",
  "updatedAt": "2021-11-19 20:39:36",
}

Error Response: Body validation error

Status Code: 400
Headers:
- Content-Type: application/json

Body:

{
  "message": "Validation Error",
  "statusCode": 400,
  "errors": {
    "content": "Content is required"
  }
}

Edit a Message

Updates and returns an existing message.

Require Authentication: true
Require proper authorization: Message must belong to the current user
Request
- Method: PUT
- URL: /messages/:message_id
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "content": "Words words words",
}
```

Successful Response

Status Code: 200
Headers:
- Content-Type: application/json

Body:

{
  "id": 1,
  "sender_id": 1,
  "receiver_id": 2,
  "content": "Words words words",
  "createdAt": "2021-11-19 20:39:36",
  "updatedAt": "2021-11-20 20:00:00",
}

Error Response: Body validation error

Status Code: 400
Headers:
- Content-Type: application/json

Body:

{
  "message": "Validation Error",
  "statusCode": 400,
  "errors": {
    "content": "Content is required"
  }
}

Error response: Couldn't find a Message with the specified id
- Status Code: 404
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "message": "Message couldn't be found",
  "statusCode": 404
}
```

Delete a Message

Deletes an existing message.

Require Authentication: true
Require proper authorization: Album must belong to the current user
Request
- Method: DELETE
- URL: /messages/:message_id
- Body: none
Successful Response
- Status Code: 200
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "message": "Successfully deleted",
  "statusCode": 200
}
```
Error response: Couldn't find a message with the specified id
- Status Code: 404
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "message": "Message couldn't be found",
  "statusCode": 404
}
```

Friend Requests

Send a Friend Request

Create and return a new friend request

Require Authentication: true
Request
- Method: POST
- URL: /friends/requests
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "friend_id": 1
}
```

Successful Response

Status Code: 200
Headers:
- Content-Type: application/json

Body:

{
  "id": 1,
  "sender_id": 1,
  "receiver_id": 2,
  "createdAt": "2021-11-19 20:39:36",
  "updatedAt": "2021-11-19 20:39:36" ,
}

Error Response: Body validation errors

Status Code: 400
Headers:
- Content-Type: application/json

Body:

{
  "message": "Validation error",
  "statusCode": 400,
  "errors": {
    "friend_id": "Friend id is required"
  }
}

Error response: Couldn't find a User with the specified id
- Status Code: 404
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "message": "User couldn't be found",
  "statusCode": 404
}
```

Get all Friend requests of the current User

Returns all the friend requests that involve the current User.

Require Authentication: true
Request
- Method: GET
- URL: /friends/requests
- Body: none

Successful Response

Status Code: 200
Headers:
- Content-Type: application/json

Body:

{
  "Sent": {
    {
      "id": 1,
      "sender_id": 1,
      "receiver_id": 2,
      "createdAt": "2021-11-19 20:39:36",
      "updatedAt": "2021-11-19 20:39:36" 
    }
  }
  "Received": {
    {
      "id": 1,
      "sender_id": 1,
      "receiver_id": 2,
      "createdAt": "2021-11-19 20:39:36",
      "updatedAt": "2021-11-19 20:39:36" 
    }
  }
}

Accept a friend request

Require Authentication: true
Require proper authorization: Friend request must be sent to the current user
Request
- Method: PUT
- URL: /friends/requests/:id
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "accept": false
}
```

Successful Response

Status Code: 200
Headers:
- Content-Type: application/json

Body:

{
  "id": 1,
  "user_id": 1,
  "friend_id": 2,
  "created_at": "2021-11-19 20:39:36",
  "updated_at": "2021-11-19 20:39:36"
}

Error response: Couldn't find a Friend Request with the specified id
- Status Code: 404
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "message": "Friend Request couldn't be found",
  "statusCode": 404
}
```

Delete a Friend Request

Require Authentication: true
Require proper authorization: Friend Request must be associated with the current user
Request
- Method: DELETE
- URL: /friends/requests/:id
- Body: none
Successful Response
- Status Code: 200
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "message": "Successfully deleted",
  "statusCode": 200
}
```
Error response: Couldn't find a Friend Request with the specified id
- Status Code: 404
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "message": "Friend Request couldn't be found",
  "statusCode": 404
}
```

Friends

Get all Friends of a user

Returns all the friends of the specified user.

Require Authentication: false
Request
- Method: GET
- URL: /users/:user_id/friends
- Body: none

Successful Response

Status Code: 200
Headers:
- Content-Type: application/json

Body:

{
  "Friends": {
    {
      "id": 1,
      "created_at": "2021-11-19 20:39:36",
      "User": {
      "id": 1,
      "username": "user123",
      "profile_pic_url": "image url"
      }
    }
  }
}

Error response: Couldn't find a user with the specified id
- Status Code: 404
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "message": "User couldn't be found",
  "statusCode": 404
}
```

Delete a Friend

Unfriends an existing friend.

Require Authentication: true
Require proper authorization: Friend must belong to the current user
Request
- Method: DELETE
- URL: /friends/:friendship_id
- Body: none
Successful Response
- Status Code: 200
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "message": "Successfully deleted",
  "statusCode": 200
}
```
Error response: Couldn't find a Friendship with the specified id
- Status Code: 404
- Headers:
  - Content-Type: application/json
- Body:
```
{
  "message": "Friendship couldn't be found",
  "statusCode": 404
}
```