Skip to content

Backend API Documentation

Jump to bottom
Gregory Isales edited this page Jul 12, 2022 · 46 revisions

All routes are prefaced with /api/

Errors

Endpoint requires authentication

Endpoints that require the 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",
  "status": 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",
  "status_code": 403
}

Session

Get the Current User

Returns information about the current user that is logged in.

  • Require Authentication: true

  • Request

    • Method: GET
    • URL: /auth/session
    • Body: none

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      "id": 1,
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@aol.net",
"location": {
  "city": "Dallas",
  "state": "Texas",
  "timezone": "GMT-5",

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: /auth/login

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "email": "john.doe@aol.net",
  "password": "secret password"
}

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "id": 1,
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@aol.net",
  "token": ""
}

  • Error Response: Invalid credentials

    • Status Code: 401

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Invalid credentials",
  "status_code": 401
}

  • Error response: Body validation errors

    • Status Code: 400

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Validation error",
  "status_code": 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: /auth/signup

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "first_name": "John",
  "last_name": "Smith",
  "email": "john.smith@gmail.com",
  "password": "secret password"
}

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "id": 1,
  "first_name": "John",
  "last_name": "Smith",
  "email": "john.smith@gmail.com",
  "token": ""
}

  • Error response: User already exists with the specified email

    • Status Code: 403

    • Headers:

      • Content-Type: application/json

    • Body:

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

  • Error response: Body validation errors

    • Status Code: 400

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Validation error",
  "status_code": 400,
  "errors": {
    "email": "Invalid email",
    "first_name": "First Name is required",
    "last_name": "Last Name is required"
  }
}

Logout a User

Log out a user

  • Require Authentication: false

  • Request

    • Method: GET/POST
    • URL: /auth/logout
    • Headers:
      • Content-Type: application/json
    • Body: none

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "User logged out",
}

Users

Get Details of a User by Id

Returns the details of a user specified by its id.

  • Require authentication: false

  • Request

    • Method: GET
    • URL: /users/:userId
    • Body: none

  • Successful Response

    • Status Code: 200
    • Headers:
      • Content-Type: application/json
    • Body:
    {
  "id": 1,
  "first_name": "John",
  "last_name": "Doe",
  "location": {
    "city": "Dallas",
    "state": "Texas",
    "timezone": "GMT-5"
  }
}

  • Errors 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",
  "status_code": 404
}

Restaurants

Get all Restaurants

  • Require authentication: false

  • Request

    • Method: GET
    • URL: /restaurants
    • Body: none

  • Successful Response

    • Status Code: 200
    • Headers:
      • Content-Type: application/json
    • Body:
    {
  "restaurants": [
  {
    "id": 1,
    "name": "Amelia's Bakery",
    "url": "amelias-bakery-dallas",
    "cuisine_type": "Baked Goods"
    "location": {
      "city": "Dallas",
      "state": "Texas",
      "timezone": "GMT-5"
    },
    "opening_time": "11am",
    "closing_time": "8pm",
    "price": 2,
    "capacity": 40,
    "address_line_1": "123 Main Street",
    "address_line_2": "",
    "location": {
      "city": "Pittsburgh",
      "state": "Pennsylvania",
      "timezone": "GMT-4"
    },
    "zip_code": 15237,
    "reservation_notes": "If you require special seating please let us know when you place your reservation.",
    "preview_image_url": "/images/j29a920ldnd0.png",
    "rating": 4.4
  }
  ]
}

Get Details of a Restaurant from its Unique Url

Returns the details of a restaurant specified by its url.

  • Require Authentication: false

  • Request

    • Method: GET
    • URL: /restaurants/:restaurantUrl
    • Body: none

  • Successful Response

    • Status Code: 200

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "id": 1,
  "name": "Amelia's Bakery",
  "url": "amelias-bakery-dallas",
  "cuisine_type": "Baked Goods"
  "location": {
    "city": "Dallas",
    "state": "Texas",
    "timezone": "GMT-5"
  },
  "opening_time": "11am",
  "closing_time": "8pm",
  "price": 2,
  "capacity": 40,
  "address_line_1": "123 Main Street",
  "address_line_2": "",
  "location": {
    "city": "Pittsburgh",
    "state": "Pennsylvania",
    "timezone": "GMT-4"
  },
  "zip_code": 15237,
  "reservation_notes": "If you require special seating please let us know when you place your reservation.",
  "preview_image_url": "/images/j29a920ldnd0.png",
  "rating": 4.4,
  "images": [ "/images/j29a920ldnd0.png", "/images/jjoaiw29.jpg", "/images/jsaowoo929.png" ]
}

  • Error response: Couldn't find a Restaurant with the specified url

    • Status Code: 404

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Restaurant couldn't be found",
  "status_code": 404
}

Get all Restaurants by Cuisine id

Get all restaurants who's cuisine id matches the specified cuisineId.

  • Require authentication: false

  • Request

    • Method: GET
    • URL: /restaurants?cuisine_id=1
    • Body: None

  • Successful Response

    • Status Code: 200
    • Headers:
      • Content-Type: application/json
    • Body:
    {
  "restaurants": [
  {
    "id": 1,
    "name": "Amelia's Bakery",
    "url": "amelias-bakery-dallas",
    "cuisine_type": "Baked Goods",
    "opening_time": "11am",
    "closing_time": "8pm",
    "price": 2,
    "capacity": 40,
    "address_line_1": "123 Main Street",
    "address_line_2": "",
    "location": {
      "city": "Dallas",
      "id": 9,
      "state": "Texas",
      "timezone": "GMT-5"
    },
    "zip_code": 15237,
    "reservation_notes": "If you require special seating please let us know when you place your reservation.",
    "preview_image_url": "/images/j29a920ldnd0.png",
    "rating": 4.4
  }
  ]
}

Get all Restaurants by Location id

Get all restaurants who's location id matches the specified location_id.

  • Require authentication: false

  • Request

    • Method: GET
    • URL: /restaurants?location_id=9
    • Body: None

  • Successful Response

    • Status Code: 200
    • Headers:
      • Content-Type: application/json
    • Body:
    {
  "restaurants": [
  {
    "id": 1,
    "name": "Amelia's Bakery",
    "url": "amelias-bakery-dallas",
    "cuisine_type": "Baked Goods",
    "opening_time": "11am",
    "closing_time": "8pm",
    "price": 2,
    "capacity": 40,
    "address_line_1": "123 Main Street",
    "address_line_2": "",
    "location": {
      "city": "Dallas",
      "id": 9,
      "state": "Texas",
      "timezone": "GMT-5"
    },
    "zip_code": 15237,
    "reservation_notes": "If you require special seating please let us know when you place your reservation.",
    "preview_image_url": "/images/j29a920ldnd0.png",
    "rating": 4.4
  }
  ]
}

Cuisine Types

Get all Cuisine Types

Returns all cuisine types and their ids.

  • Require authentication: false

  • Request

    • Method: GET
    • URL: /cuisines
    • Body: none

  • Successful Response

    • Status Code: 200
    • Headers:
      • Content-Type: application/json
    • Body:
    {
  "cuisines": [
    {
      "id": 1,
      "type": "Mexican"
    },
    {
      "id": 2,
      "type": "American"
    },
    {
      "id": 3,
      "type": "Chinese"
    }]
}

Occasions

Get all Occasions

Get a list of all the possible occasions

  • Require Authentication: false

  • Request

    • Method: GET
    • URL: /occasions
    • Body: none

  • Successful Response

    • Status Code: 200
    • Headers:
      • Content-Type: application/json
    • Body: 
      {
  "occasions": [
    "Birthday",
    "Anniversary",
    "Date night",
    "Business meal",
    "Celebration"
   ]
}

Reservations

Create a Reservation

Creates and returns a new reservation.

  • Require Authentication: false

  • Request

    • Method: POST
    • URL: /reservations
    • Headers:
      • Content-Type: application/json
    • Body: 
      {
  "restaurant_id": 1,
  "party_size": 2,
  "timeslot": "18:30:00",
  "day": "2018-05-29",
  "special_request": "Please give the lobster a helicopter tour of the city prior to it being cooked.",
  "occasion_id": 3
}

  • Successful Response

    • Status Code: 201
    • Headers:
      • Content-Type: application/json
    • Body: 
      {
  "id": 1,
  "user_id": 3,
  "restaurant_id": 1,
  "timeslot": "18:30:00",
  "day": "2018-05-29",
  "special_request": "Please give the lobster a helicopter tour of the city prior to it being cooked.",
  "review_link": "/reviews/kawjdnawdnkn29ajkwd"
}

  • Error Response: Request body not provided

    • Status Code: 400
    • Headers:
      • Content-Type: application/json
    • Body: 
      {
  "message": "Request body is required",
  "status_code": 400
}

  • Error Response: Couldn't find a restaurant with the specified id

    • Status Code: 404
    • Headers:
      • Content-Type: application/json
    • Body: 
      {
  "message": "Restaurant couldn't be found",
  "status_code": 404
}

  • Error Response: Body validation error

    • Status Code: 400
    • Headers:
      • Content-Type: application/json
    • Body: 
      {
  "message": "Validation Error",
  "status_code": 400,
  "errors": {
    "party_size": "Party size must be 1 or greater",
    "day": "Day must be a valid date",
    "timeslot_id": "Timeslot id must be valid",
    "occasion_id": "Occasion id must be valid"
  }
}

  • Error Response: Restaurant cannot accommodate reservation

    • Status Code: 400
    • Headers:
      • Content-Type: application/json
    • Body: 
      {
  "message": "Restaurant cannot accommodate this party size at the specified time",
  "status_code": 400
}

Get User's Reservations

Returns a list of the User's reservations

  • Require authentication: true

  • Request

    • Method: GET
    • URL: /reservations/user

  • Successful Response

    • Status Code: 200
    • Headers:
      • Content-Type: application/json
    • Body: 
      {
   "reservations": [
   {
     "id": 1,
     "user_id": 3,
     "restaurant_id": 1,
     "timeslot": "18:30:00",
     "day": "2018-05-29",
     "special_request": "Please give the lobster a helicopter tour of the city prior to it being cooked.",
     "review_link": "/reviews/kawjdnawdnkn29ajkwd"
   }]
}

Delete a Reservation

Delete a reservation by id

  • Require authentication: true

  • Require proper authentication: Reservation must belong to the current user

  • Request

    • Method: DELETE
    • URL: /reservations/:reservationId
    • Body: none

  • Successful Response

    • Status Code: 200
    • Headers:
      • Content-Type: application/json
    • Body: 
      {
  "message": "Successfully deleted reservation",
  "status_code": 200
}

  • Error Response: Reservation does not belong to current user

    • Status Code: 401
    • Headers:
      • Content-Type: application/json
    • Body: 
      {
  "message": "No permission to delete this reservation",
  "status_code": 401
}

  • Error Response: Couldn't find a reservation with the specified id

    • Status Code: 404
    • Headers:
      • Content-Type: application/json
    • Body: 
      {
  "message": "Reservation does not exist",
  "status_code": 404
}

Favorites

Get User's Favorite Restaurants

Returns the list of a User's favorited restaurants.

  • Require authentication: True

  • Request

    • Method: GET
    • URL: /my/favorites
    • Body: none

  • Successful Response

    • Status Code: 200
    • Headers:
      • Content-Type: application/json
    • Body:
    {
  "restaurants": [
      {
        "id": 1,
        "url": "restaurant-name-location",
        "name": "McDonald's",
        "cuisine_type": "Fast Food",
        "rating": 2.5,
        "price": 2,
        "location": {
          "id" : 9
          "city": "Dallas",
          "state": "Texas",
          "timezone": "GMT-5"
        },
        "preview_image_url": "dbhost.image3456.jpg"
      }
  ]
}

Add a Restaurant to User's Favorites

Adds a Restaurant to User's Favorites

  • Require authentication: True
  • Request
    • Method: POST
    • URL: /my/favorites
    • Headers: application/json
    • Body:
   {
     "restaurant_id": 1
   }
  • Successful Response
    • Status Code: 200
    • Headers:
      • Content-Type: application/json
    • Body:
   {
     "id": 1,
     "user_id": 1,
     "restaurant_id": 1
   }
  • Error response: Couldn't find a Restaurant with the specified id
    • Status Code: 404
    • Headers:
      • Content-Type: application/json
    • Body:
{
  "message": "Restaurant couldn't be found",
  "status_code": 404
}

Remove a Restaurant from the User's Favorites

Removes a Restaurant from the User's Favorites

  • Require authentication: True

  • Request

    • Method: DELETE
    • URL: /my/favorites/:restaurantId
    • Body: none

  • Successful Response

    • Status Code: 200
    • Headers:
      • Content-Type: application/json
    • Body:
   {
     "message": "Successfully deleted",
     "status_code": 200
   }
  • Error response: Couldn't find a Restaurant with the specified id
    • Status Code: 404
    • Headers:
      • Content-Type: application/json
    • Body:
{
  "message": "Restaurant couldn't be found in favorites",
  "status_code": 404
}

Ratings/Reviews

Get User's Ratings and Reviews

Returns the User's Ratings and Reviews.

  • Require authentication: True

  • Request

    • Method: GET
    • URL: /reviews/user
    • Body: none

  • Successful Response

    • Status Code: 200
    • Headers:
      • Content-Type: application/json
    • Body:
    {
  "reviews": [
      {
        "id": 1,
        "user_id": 1,
        "restaurant": {
          "id": 1,
          "name": "Amelia's Bakery",
          "url": "amelias-bakery-dallas",
          "cuisine_type": "Baked Goods",
          "location": {
            "city": "Dallas",
            "state": "Texas",
            "timezone": "GMT-5"
          },
        },
        "overall_rating": 2,
        "food_rating": 3,
        "service_rating": 1,
        "ambience_rating": 1,
        "value_rating": 2,
        "review_text": "It was really underwhelming, but the food was okay."
      }
  ]
}

Get all Ratings and Reviews of a Restaurant

Returns the Ratings and Reviews of a Restaurant specified by its id.

  • Require authentication: False

  • Request

    • Method: GET
    • URL: /restaurants/:restaurantUrl/reviews
    • Body: none

  • Successful Response

    • Status Code: 200
    • Headers:
      • Content-Type: application/json
    • Body:
    {
  "reviews": [
      {
          "id": 1,
          "user": {
              "id": 1,
              "first_name": "John",
              "last_name": "Doe",
              "location": {
                  "city": "Dallas",
                  "state": "Texas",
                  "timezone": "GMT-5"
              }
          },
          "restaurant_id": 1,
          "overall_rating": 2,
          "food_rating": 3,
          "service_rating": 1,
          "ambience_rating": 1,
          "value_rating": 2,
          "review_text": "It was really underwhelming, but the food was okay."
      }
  ]
}
    • Error response: Couldn't find a Restaurant with the specified id
    • Status Code: 404
    • Headers:
      • Content-Type: application/json
    • Body:
{
  "message": "Restaurant couldn't be found",
  "status_code": 404
}

Get details of a Review by Id

Returns the details of a Review with the specified id

  • Require authentication: False

  • Request

    • Method: GET
    • URL: /reviews/:reviewId
    • Body: none

  • Successful Response

    • Status Code: 200
    • Headers:
      • Content-Type: application/json
    • Body:
    {
  "id": 1,
  "user": {
      "id": 1,
      "first_name": "John",
      "last_name": "Doe",
      "location": {
          "city": "Dallas",
          "state": "Texas",
          "timezone": "GMT-5"
      }
  },
  "restaurant": {
      "id": 1,
      "name": "Amelia's Bakery",
      "url": "amelias-bakery-dallas",
      "cuisine_type": "Baked Goods",
      "location": {
          "city": "Dallas",
          "state": "Texas",
          "timezone": "GMT-5"
      },
  },
  "overall_rating": 2,
  "food_rating": 3,
  "service_rating": 1,
  "ambience_rating": 1,
  "value_rating": 2,
  "review_text": "It was really underwhelming, but the food was okay."
}

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

    • Status Code: 404
    • Headers:
      • Content-Type: application/json
    • Body:
{
  "message": "Review couldn't be found",
  "status_code": 404
}

Retrieve Reservation details to use in a Review with the Review Link

Returns the details of a Reservation to use in a Review with the specified Review Link URL

  • Require authentication: False
  • Request
    • Method: POST
    • URL: /reviews/new
    • Headers:
    • Content-Type: application/json
    • Body:
{
  "url": "kawjdnawdnkn29ajkwd"
}

  • Successful Response

    • Status Code: 200
    • Headers:
      • Content-Type: application/json
    • Body:
    {
  "user": {
      "id": 1,
      "first_name": "John",
      "last_name": "Doe",
  },
  "restaurant": {
      "id": 1,
      "name": "Amelia's Bakery",
      "location": {
            "city": "Dallas",
            "state": "Texas",
            "timezone": "GMT-5"
      },
  }
}
    • Error response: Couldn't find a Reservation with the specified review link
    • Status Code: 404
    • Headers:
      • Content-Type: application/json
    • Body:
{
  "message": "Reservation couldn't be found",
  "status_code": 404
}

Create a Review

Creates and Returns a new Review

  • Require authentication: True
  • Request
    • Method: POST
    • URL: /reviews
    • Headers: application/json
    • Body:
   {
     "restaurant_id": 1,
     "overall_rating": 2,
     "food_rating": 3,
     "service_rating": 1,
     "ambience_rating": 1,
     "value_rating": 2,
     "review_text": "It was really underwhelming, but the food was okay."
   }
  • Successful Response
    • Status Code: 200
    • Headers:
      • Content-Type: application/json
    • Body:
   {
     "id": 1,
     "user_id": 1,
     "restaurant_id": 1,
     "overall_rating": 2,
     "food_rating": 3,
     "service_rating": 1,
     "ambience_rating": 1,
     "value_rating": 2,
     "review_text": "It was really underwhelming, but the food was okay."
   }
  • Error response: Body validation errors

    • Status Code: 400

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Validation error",
  "status_code": 400,
  "errors": {
    "restaurant": "A restaurant with that id does not exist",
    "overall_rating": "An overall rating is required",
    "*_rating": "Rating must be an integer between 0 and 5"
  }
}

Edit a Review

Updates and Returns a User's Review with the specified id

  • Require authentication: True
  • Require proper authorization: Review must belong to the current user
  • Request
    • Method: PUT
    • URL: /reviews/:reviewId
    • Headers: application/json
    • Body:
   {
     "restaurant_id": 1,
     "overall_rating": 2,
     "food_rating": 3,
     "service_rating": 1,
     "ambience_rating": 1,
     "value_rating": 2,
     "review_text": "It was really underwhelming, but the food was okay."
   }
  • Successful Response
    • Status Code: 200
    • Headers:
      • Content-Type: application/json
    • Body:
   {
     "id": 1,
     "user_id": 1,
     "restaurant_id": 1,
     "overall_rating": 2,
     "food_rating": 3,
     "service_rating": 1,
     "ambience_rating": 1,
     "value_rating": 2,
     "review_text": "It was really underwhelming, but the food was okay."
   }
  • Error response: Couldn't find a Review with the specified id
    • Status Code: 404
    • Headers:
      • Content-Type: application/json
    • Body:
{
  "message": "Review couldn't be found",
  "status_code": 404
}
  • Error response: Body validation errors

    • Status Code: 400

    • Headers:

      • Content-Type: application/json

    • Body:

      {
  "message": "Validation error",
  "status_code": 400,
  "errors": {
    "restaurant": "A restaurant with that id does not exist",
    "overall_rating": "An overall rating is required",
    "*_rating": "Rating must be an integer between 0 and 5"
  }
}

Delete a Review

Deletes a Review posted by the User specified by id

  • Require authentication: True

  • Require proper authorization: Review must belong to the current user

  • Request

    • Method: DELETE
    • URL: /reviews/:reviewId
    • Body: none

  • Successful Response

    • Status Code: 200
    • Headers:
      • Content-Type: application/json
    • Body:
   {
     "message": "Successfully deleted review",
     "status_code": 200
   }
  • Error response: Couldn't find a Review with the specified id
    • Status Code: 404
    • Headers:
      • Content-Type: application/json
    • Body:
{
  "message": "Review couldn't be found",
  "status_code": 404
}

Clone this wiki locally