Skip to content

API Docs

Jump to bottom
Tina edited this page Nov 5, 2024 · 1 revision

Stack Overflow Replica

API Documentation

USER AUTHENTICATION/AUTHORIZATION

All endpoints that require athentication

All endpoints that require a current user to be logged in

  • Primarily handled by flask-login. Custom error handling if neccessary.

  • Request: endpoints that require authentication

  • Error Response: Require authentication

    • Status Code: 401

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Authentication required"
}

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)

  • Primarily handled by flask-login. Custom error handling if necessary.

  • Request: endpoints that require proper authorization

  • Error Response: Require proper authorization

    • Status Code: 403

    • Headers:

      • Content-Type: application/json

    • Body:

      {
    "message": "Forbidden"
}

Get the Current User

Primarily handled by flask-login. Custom response route if necessary.

  • Require Authentication: false

  • Request

    • Method: GET
    • Route path: /api/session
    • Body: none

  • Successful Response when there is a logged in user

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "user": {
    "id": 1,
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@gmail.com",
    "username": "JohnSmith"
  }
}

  • Successful Response when there is no logged in user

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "user": null
}

Log In a User

Primarily handled by flask-login. Custom response route if necessary.

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

  • Require Authentication: false

  • Request

    • Method: POST

    • Route path: /api/session

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "credential": "john.smith@gmail.com",
  "password": "secret password"
}

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "user": {
    "id": 1,
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@gmail.com",
    "username": "JohnSmith"
  }
}

  • Error Response: Invalid credentials

    • Status Code: 401

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Invalid credentials"
}

      Consider individual error responses for specific invalid fields

      {
    "message": "Invalid credentials",
    "credential": "Email or username does not exist",
    "password": "Incorrect password"
}

  • Error response: Body validation errors

    • Status Code: 400

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Bad Request", // (or "Validation error" if generated by Sequelize),
  "errors": {
    "credential": "Email or username 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

    • Route path: /api/users/register

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "firstName": "John",
  "lastName": "Smith",
  "email": "john.smith@gmail.com",
  "username": "JohnSmith",
  "password": "secret password"
}

  • Successful Response

    • Status Code: 201

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "user": {
    "id": 1,
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@gmail.com",
    "username": "JohnSmith"
  }
}

  • Error response: User already exists with the specified email or username

    • Status Code: 500

    • Headers:

      • Content-Type: application/json

    • Body:

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

  • Error response: Body validation errors

    • Status Code: 400

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Bad Request", // (or "Validation error" if generated by Sequelize),
  "errors": {
    "email": "Invalid email",
    "username": "Username is required",
    "firstName": "First Name is required",
    "lastName": "Last Name is required",
    "password": "Password is required" or "Passwords must match",
  }
}

Questions

Get all Questions

Returns all questions

  • Require Authentication: false

  • Request

    • Method: Get
    • Route path: /api/questions
    • Body: none

  • Succesfful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
    "Questions": [
        {
        "id": 1,
        "user_id": 1,
        "content": "Is this a sample question?",
        "created_at": "2024-10-31 14:18:30",
        "updated_at": "2024-10-31 14:18:30",
        }

    ]
}

Get all Questions by the Current User

Returns all the questions created by the current user.

  • Require authentication: true

  • Request

    • Method: GET
    • Route path: /api/questions/current
    • Body: none

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json *Body :
      {
    "Questions": [
        {
        "id": 1,
        "user_id": 1,
        "content": "Is this a sample question?",
        "created_at": "2024-10-31 14:18:30",
        "updated_at": "2024-10-31 14:18:30",
        
        }
    ]
}

Get details of a Question from an id

Returns the details of a question specified by its id.

  • Require Authentication: false

  • Request

    • Method: GET
    • Route path: /api/questions/int:question_id
    • Body: None

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
    "id": 1,
    "user_id": 1,
    "content": "Is this a sample question?",
    "created_at": "2024-10-31 14:18:30",
    "updated_at": "2024-10-31 14:18:30",
    "Comments": [
        {
            "id": 1,
            "user_id": 1,
            "content": "This is a sample comment.",
        }
    ],
    "Topics": [
        {
            "id":1,
            "name": "Python"
        }
    ],
    "User": {
        "id":1,
        "username": "JohnSmith"
    }
}

  • Error response: Couldn't find a Question with the specified id

    • Status Code: 404

    • Headers:

      • Content-Type: application/json

    • Body:

      {
    "message": "Question couldn't be found"
}

Create a Question

Creates and returns a new question.

  • Require Authentication: true

  • Request

    • Method: POST

    • Route path: /api/questions

    • Headers:

      • Content-Type: application/json

    • Body:

      {
    "content": "Is this a sample question?",
    "Topics":[
        {
            "name": "Python"
        },
        {
            "name": "JavaScript"
        }
    ]
}

  • Successful Response

    • Status Code: 201

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "id": 1,
  "user_id": 1,
  "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": "Bad Request", // (or "Validation error" if generated by Sequelize),
  "errors": {
    "content": "Content is required",
  }
}

Edit a Question

Updates and returns an existing question

  • Require Authentication: true

  • Require proper authorization: Question must belong to current user

  • Request

    • Method: PUT
    • Route path: /api/spots/<int: spotId>

Delete a question

Deletes an existing question

  • Require Authentication: true

  • Require proper authorization: Question must belong to current user

  • Request

    • Method: DELETE
    • Route path: /api/spots/<int: spotId>

Comments

Get all Comments by Question id

Returns all the comments for a Question by the specified id

  • Require Authentication: false
  • Request
    • Method: GET
    • Route path: /api/questions/<int: question_id>/comments

Create a Comment for a Question based on the Question's id

Create and return a new comment for a question specified by id.

  • Require Authentication: true
  • Request
    • Method: POST
    • Route path: /api/questions/<int: question_id>/comments

Edit a comment

Update an return an existing comment

  • Require Authentication: true
  • Require proper authorization: Comment must belong to the current user
  • Request
    • Method: PUT
    • Route path: /api/comments/<int: comment_id>

Delete a comment

Delete an existing comment.

  • Require Authentication: true
  • Require proper authorization: Comment must belong to the current user
  • Request
    • Method: DELETE
    • Route path: /api/comments/<int: comment_id>

Saves

Get all of the Current User's Saves

Return all the saves that the current user has made.

  • Require Authentication: true
  • Request
    • Method: GET
    • Route path: /api/saves/current

Add a question to the Current User's Saves

Update and return the current user's saves

  • Require Authentication: true
  • Require proper authorization: Save must belong to the current user
  • Request
    • POST
    • Route path: /api/saves/<int: save_id>

Remove a question from the Current User's Saves

Remove an existing save.

  • Require Authentication: true
  • Require proper authorization: Save must belong to the current user
  • Request
    • DELETE
    • Route path: /api/saves/<int: save_id>

Topics

Get all Topics by Question id

Return all the topics for a question specified by id

  • Require Authentication: false
  • Request
    • Method: GET
    • Route path: /api/questions/<int: question_id>/topics

Add a Topic to a Question by id

  • Require Authentication: true
  • Require proper authorization: Question must belong to the current user
  • Request
    • Method: POST
    • Route path: /api/questions/<int: question_id>/topics

Delete a Topic to a question by id

  • Require Authentication: true
  • Require proper authorization: Question must belong to the current user
  • Request
    • Method: DELETE
    • Route path: /api/questions/<int: question_id>/topics

Update Topics of a Question by id

  • Require Authentication: true
  • Require proper authorization: Question must belong to the current user
  • Request

    • Method: PUT

    • Route path: /api/questions/<int: question_id>/topics

    • Combination of POST and DELETE. Look into how to effectively do this

Clone this wiki locally