API Documentation

betterReads is a social media platform that allows users to connect with other readers alike, search its database of books, browse recommendations, and manage their own library.

1️⃣ Backend deployed at AWS_ELASTIC_BEANSTALK

1️⃣ Getting started

To get the server running locally:

Clone this repo
npm install to install all required dependencies
npm run server to start the local server
npm start only for production
npm run test to start server using testing environment

Seeding for tests

seed data is in database/seeds/ (seeds have been removed)

knex migrate:up --env=testing
knex migrate:up --env=testing
knex migrate:up --env=testing
knex seed:run --env=testing --specific=001-users.js
knex seed:run --env=testing --specific=001-books.js
knex migrate:up --env=testing
knex seed:run --env=testing --specific=002-user-books.js
knex migrate:up --env=testing
knex seed:run --env=testing --specific=002-user-shelves.js
knex migrate:up --env=testing

Express

Simple routing
Event driven features
Uses Javascript, an omnipresent language in web development
Large Community Support

2️⃣ Endpoints

🚫This is a placeholder, replace the endpoints, access control, and description to match your project

User Authentication Routes

Method	Endpoint	Access Control	Description
POST	`/api/auth/signup`	all users	Returns message and user object.

Body Required

{  
  fullName: STRING,
  emailAddress: STRING, 
  password: STRING 
}

Returns

{
  message: "successfully registered user",
  user: {
    id:  {user id},
    fullName: {user full name},
    emailAddress: {user email address},
    image: {user image in blob form},
    googleID: {user Google ID},
    facebookID: {user Facebook ID}
  }
}

Method	Endpoint	Access Control	Description
POST	`/api/auth/signin`	all users	Returns message and user object.

Body Required

{
  emailAddress: STRING,
  password: STRING
}

Returns

{
  message: "successfully logged in",
  token: {json web token},
  user: {
  	  id:  {user id},
	  fullName: {user full name},
	  emailAddress: {user email address},
	  image: {user image in blob form},
	  googleID: {user Google ID},
	  facebookID: {user Facebook ID}
	}
}

Authentication has been updated from sessions to more secure JSON web tokens. Here is what you need to do to ustilize them

Set up axioswithauth()

- create a file called axiosWithAuth
- within this file, write the following function

	  const axiosWithAuth = () => {
	  const token = localStorage.getItem("token")
	  	return axios.create({
			baseURL: "https://api.readrr.app/",
			headers: { authorization: token }
		})	
	  }

Method	Endpoint	Access Control	Description
POST	`/api/auth/reset/requestreset/`	all users	Returns a message and sends an email to the user (if the user exists) which has a url containing a token needed for the second endpoint.

Required Body

    {
        "email": "user email"
    }

Returns

    {
        message: "Request received, a link has been sent to the requested email",
    }

Method	Endpoint	Access Control	Description
POST	`/api/auth/reset/`	all users	Updates user password with the requested password

Body Requires

    {
        "token": "{ user password reset token from url in sent email}",
        "password": "{ user requested password }"
    }

Returns

    {
        "message": "Successfully updated user info"
    }

Use Local Storage

hit the sign in endpoint to get a token for the user
store the token in local storage with localStorage.setItem("token", ${res.data.token})

Protected Routes

User Genres

Method	Endpoint	Access Control	Description
POST	`/api/genre`	all users	Returns genre info for registered users.

Body Required

{
	genre: STRING,
	userId: INTEGER
}

Returned

{
	message: "genre added successfully",
	genre: { genre }
}

Method	Endpoint	Access Control	Description
PUT	`/api/genre/:userId/:genreId`	all users	Returns updated genre info

Body Required

{
	userId: INTEGER,
	genreName: { genre }
}

Returned

{
    "message": "genre updated successfully",
    updatedGenre: { updatedGenre }
}

Search Google Books, Search in our Books Table, and Post to our Books Table

Method	Endpoint	Access Control	Description
GET	`/api/books`	all users	Returns all books that meet query criteria (title, author)
GET	`/api/books/:bookId`	all users	Returns a single book object
POST	`/api/books`	all users	Returns No Content

Body Required

{
  googleId: STRING,
  title: STRING,
  authors: STRING,
  publisher: STRING,
  publishedDate: STRING,
  description: STRING,
  isbn10: STRING,
  isbn13: STRING,
  pageCount: INTEGER,
  categories: STRING,
  thumbnail: STRING,
  smallThumbnail: STRING,
  language: STRING,
  webReaderLink: STRING,
  textSnippet: STRING,
  isEbook: BOOLEAN,
  averageRating: DECIMAL
}

User Library

Method	Endpoint	Access Control	Description
GET	`/api/:userId/library`	all users	Returns all books of user by the requested id
GET	`/api/:userId/library/:id`	all users	Returns a single book by a requested id
GET	`/api/:userId/library/favorites`	all users	Returns all favorite books of a user by the requested id

Method	Endpoint	Access Control	Description
PUT	`/api/:userId/library`	all users	updates an aspect of a requested user book, returns updated book

Body (All required)

{
  "bookId": "INTEGER Foreign key, from books",
  "readingStatus": "INTEGER",
  "favorite": "BOOLEAN",
  "dateStarted": "STRING MM/DD/YYYY",
  "dateEnded": "STRING MM/DD/YYYY",
  "userRating": "DECIMAL"
}

Returns the body of the request with a the primary key (integer) for the book in the table, a userId (integer) and a date added (standard date format).

Method	Endpoint	Access Control	Description
DELETE	`/api/:userId/library`	all users	Returns No Content

Body Required

{
  bookId: "FOREIGN KEY from books"
}

Method	Endpoint	Access Control	Description
POST	`/api/:userId/library`	all users	Return added book object

Body Required

{
  book: { book },
  readingStatus: INTEGER,
  favorite: BOOLEAN
}

Returns

    {
        id: "primary key",
        bookId: "id of the added book",
        userId: "id of the user to whom's library the book was added",
        readingStatus: "reading status of the added book",
        dateStarted: "date the book was started, will always be null immediately after a post",
        dateEnded: "date the book was ended, will always be empty immediately after a post",
        dateAdded: "date the book was added, defaults to the exact time of the post request",
        favorite: "favorite status of the added book",
        userRating: "average user rating of the added book, pulled for the GoogleBooks api",
        googleId: "google id of the added book, pulled from the GoogleBooks api",
        title: "title of the added book",
        authors: "authors of the added book",
        publisher: "publisher of the added book",
        publishedDate: "publish date of the added book",
        description: "description of the added book, pulled from the GoogleBooks api",
        isbn10: "ISBN number of the added book, pulled from the GoogleBooks api",
        isbn13: "another ISBN, pulled from the GoogleBooks api",
        pageCount: "page count of the added book, pulled form the GoogleBooks api",
        categories: "categories for the added book, pulled from the GoogleBooks api",
        thumbnail: "thumbnail for the added book, pulled from the GoogleBooks api",
        smallThumbnail: "small thumbnail of the added book, pulled form the GoogleBooks api",
        language: "language of the added book, pulled from the GoogleBooks api",
        webReaderLink: "web reader link for the added book, pulled from the GoogleBooks api",
        textSnippet: "a snippet fo text from the added book, pulled form the GoogleBooks api",
        isEbook: "boolean reflecting whether the added book is in ebook form, pulled from the GoogleBooks api",
        averageRating: "average rating of the added book, pulled from the GoogleBooks api"
    }

User's shelves

Method	Endpoint	Access Control	Description
GET	`/api/shelves/user/:userId`	all users	Returns all user's shelves
GET	`/api/shelves/:shelfId`	all users	Returns a user's selected shelf, containing all of the books on that shelf
DELETE	`/api/shelves/:shelfId`	all users	Return deleted shelf id
POST	`/api/shelves/user/:userId`	all users	Returns an empty shelf

Body Required for POST

{
  shelfName: STRING,
  isPrivate: BOOLEAN
}

Method	Endpoint	Access Control	Description
PUT	`/api/shelves/:shelfId`	all users	Return changed shelf

Body Required

{
  shelfName: STRING,
  isPrivate: BOOLEAN
}

User's books on a shelf

Method	Endpoint	Access Control	Description
DELETE	`/api/booksonshelf/shelves/:shelfId/:bookId`	all users	Returns deleted book id
POST	`/api/booksonshelf/shelves/:shelfId`	all users	Returns shelf object with book object in shelf
PUT	`/api/booksonshelf/shelves/:shelfId`	all users	Returns updated shelf id and the book id newly associated with it
GET	`/api/booksonshelf/shelves/:shelfId`	all users	Returns all books on a requested shelf
GET	`/api/booksonshelf/user/:userId/shelves/allbooks`	all users	Returns all user's shelves with the books

Body Required

-- DELETE /api/booksonshelf/shelves/:shelfId

{
  bookId: FOREIGN KEY from books
}

-- POST /api/booksonshelf/shelves/:shelfId

{
  book: { book },
  readingStatus: INTEGER,
  favorite: BOOLEAN,
  userRating: DECIMAL
}

-- PUT /api/booksonshelf/shelves/:shelfId

{
  bookId: FOREIGN KEY from books,
  newShelfId: ShelfID from updated shelf
}

-- GET /api/booksonshelf/shelves/:shelfId

{
  bookId: FOREIGN KEY from books
}

Recommendations

Method	Endpoint	Access Control	Description
GET	`/api/:userId/recommendations`	all users	Returns recommendations based on the requested user's library

Returns

    {
        "message": "recommendations retrieved successfully",
        "recommendations": { recommendations }
    }

Method	Endpoint	Access Control	Description
POST	`/api/:userId/recommendations`	all users	Returns recommendations based on the requested books

Requires

    {
        "books": [ array of books ]
    }

Returns

    {
        "message": "recommendations retrieved successfully",
        "recommendations": { recommendations }
    }

Reading Statistics

Method	Endpoint	Access Control	Description
GET	`/api/stats`	All Users, no token required	Returns reading statistics for all users

Returns

    {
        "message": "user-wide stats retrieved",
        "toBeRead": "INTEGER number of books on all users' to be read shelves",
        "inProgress": "INTEGER number of books on all users' in progress shelves",
        "completed": "INTEGER number of books on all users' completed shelves"    
    }

Method	Endpoint	Access Control	Description
GET	`api/stats/:userId`	All Users, no token required	Returns reading statistics of requested user

Returns

    {
        "message": "stats for the rquested user retrieved",
        "toBeRead": "INTEGER number of books on a user's to be read shelf",
        "inProgress": "INTEGER number of books on a user's in progress shelf",
        "completed": "INTEGER number of books on a user's completed shelf"
    }

Book Tagging

Method	Endpoint	Access Control	Description
POST	`api/tags/userBooksId`	All Users	Adds a tag(s) to the requested user book

Body Required

    {
        "tags": "STRING comma seperated tags here, comma seperated tags here"
    }

Returns

    {
        "message": "tag(s) successfully added"
    }

Method	Endpoint	Access Control	Description
GET	`api/stats/:userBooksId`	All Users	Returns an array of all tags for the requested user book

Returns

    {
        "tags": [
            {
                "tagId": "tagId",
                "bookTagName": "name of tag for specific user book",
                "userBooksId": "id of the user book that the tag corresponds to"
            }, ...
        ]
    }

Method	Endpoint	Access Control	Description
GET	`api/tags/user/:userId`	All Users	Returns an array of all books with tags requested user

Returns

    {
        "tags": [
            {
                "userBooksId": "id of the user book that the tag corresponds to",
                "bookTagName": "name of tag for specific user book",
                "userId": "user id that the book and tag correspond to",
                "tagId": "tagId",
            }, ...
        ]
    }

Method	Endpoint	Access Control	Description
PUT	`api/tags/:tagId`	All Users	Updates a requested tagname

Body Required

    {
        "newTag": "STRING new tag name"
    }

Returns

    {
        "message": "tag updated successfully"
    }

Method	Endpoint	Access Control	Description
DELETE	`api/tags/:tagId`	All Users	Deletes the requested tag

Body Returned

    {
        "message": "tag deleted"
    }

Data Model

2️⃣ USERS

{
  "id": "INTEGER",
  "emailAddress": "STRING",
  "password": "STRING"
}

2️⃣ GENRES

{
  "id": "INTEGER",
  "genre": "STRING"
}

2️⃣ USERGENRE

{
  "id": "INTEGER",
  "genreName": "STRING",
  "userId": "INTEGER foreign key in USER table"
}

2️⃣ BOOKS

{
  "id": "INTEGER",
  "googleId": "STRING",
  "title": "STRING",
  "authors": "STRING",
  "publisher": "STRING",
  "publishDate": "STRING",
  "description": "STRING",
  "isbn10": "STRING",
  "isbn13": "STRING",
  "pageCount": "INTEGER",
  "categories": "STRING",
  "thumbnail": "STRING",
  "smallThumbnail": "STRING",
  "language": "STRING",
  "webRenderLink": "STRING",
  "textSnippet": "STRING",
  "isEbook": "BOOLEAN",
  "averageRating": "DECIMAL"
}

2️⃣ USERBOOKS

{
  "id": "INTEGER",
  "bookId": "INTEGER foreign key in GOOGLEBOOKS table",
  "userId": "INTEGER foreign key in USERS table",
  "readingStatus": "INTEGER (NULLABLE)",
  "dateStarted": "DATETIME (NULLABLE)"
  "dateEnded": "DATETIME (NULLABLE)",
  "dateAdded": "DATETIME (AUTOMATICALLY GENERATED)",
  "favorite": "BOOLEAN (NULLABLE)"
}

2️⃣ USERSHELVES

{
  id"": "INTEGER",
  "userId": "INTEGER foreign key in USERS table",
  "shelfName": "STRING",
  "isPrivate": "BOOLEAN (NULLABLE)"
}

2️⃣ USERBOOKSONASHELF

{
  "id": "INTEGER",
  "bookId": "INTEGER foreign key in BOOKS table",
  "shelfId": "INTEGER foreign key in USERSHELVES table"
}

2️⃣ Actions

Users

add(user object) -> Returns the created user

findBy(filter) -> Return all users matching filter

count() -> Return total number of users

Books

findBy(filter) -> returns an array of books associated to filter

getAll() -> Returns all books

add(book object) -> Returns a single book

findById(id) -> Returns a single book

UserBooks

findBy(filter) -> Returns an array book from user's library

add(book) -> Returns a single book

findById(bookId) -> Finds book by bookId

findFavorites(userId) -> Returns array of favorite books

isBookInUserBooks(userId, googleId) -> Checks if book is already in user's library

findByUserId(userId) -> Return all books in user's library

findDetailByUserId(userId, bookId) -> Return a single book with full details

find(userId, bookId) -> Return a single book with no details

update(userId, bookId, update) -> Return a single book with full details

remove(userId, bookId) -> Returns nothing

UserShelves

findBy(filter) -> Returns an array of bookshelves

findByUser(id) -> Returns an array of bookshelves

returnShelfId(userId) -> Returns an array of shelf ids

add(shelf) -> Returns a single bookshelf

update(updatedShelf, shelfId) -> Returns a single bookshelf

remove(shelfId) -> Returns nothing

UserBooksOnAShelf

findBook(shelfId, bookId) -> Returns books on shelf

findAllBooks(shelfId) -> Return all books on shelf

returnEveryShelfFrom(userId) -> Returns all books from user's shelves

findBooksIn(shelfId) -> Returns books on shelf

findById(id) -> Returns shelf with book

addBooks(book) -> Returns book

remove(bookId, shelfId) -> Returns nothing

removeAll(bookId, userId) -> Returns removed shelf id

AllUserData

booksFor(userId) -> Returns all books for user

shelvesFor(userId) -> Returns all shelves for user

find(userId) -> Returns number of books on a shelf

findBooksIn(shelfId) -> Returns all books on shelf

findBy(userId) -> Returns everything about user

3️⃣ Environment Variables

In order for the app to function correctly, the user must set up their own environment variables.

create a .env file that includes the following:

* DB_ENV - set to "development" until ready for "production"
* HOST - set to host (i.e., localhost)
* DB_USER - set to username on your postgres server
* PASSWORD - set to password for user on your postgres server
* DB - set to database name for your postgres server
* TEST_DB - set to test database name for your postgres testing server

* SESSION_NAME - ...
* SESSION_SECRET - ...
* GOOGLE_CLIENT_ID - this is generated in your google account
* GOOGLE_CLIENT_SECRET - this is generated in your google account
* FACEBOOK_CLIENT_ID - this is generated in your facebook account
* FACEBOOK_CLIENT_SECRET - this is generated in your facebook account

* BASE_URL - set in "production" for elastic beanstock
* FAIL_URL - set in "production" for elastic beanstock
* SUCCESS_URL - set in "production" for elastic beanstock
* GOOGLE_CALLBACK - set in "production" for elastic beanstock
* FACEBOOK_CALLBACK - set in "production" for elastic beanstock

* NODE_ENV - set to "development" until ready for "production"
* RDS_HOSTNAME - set in "production"
* DATA_SCIENCE - set in "production"
* DATE_SCIENCE_TOTAL - set in "production"

Contributing

When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.

Please note we have a code of conduct. Please follow it in all your interactions with the project.

👾 Issue/Bug Request 👾

If you are having an issue with the existing project code, please submit a bug report under the following guidelines:

Check first to see if your issue has already been reported.
Check to see if the issue has recently been fixed by attempting to reproduce the issue using the latest master branch in the repository.
Create a live example of the problem.
Submit a detailed bug report including your environment & browser, steps to reproduce the issue, actual and expected outcomes, where you believe the issue is originating from, and any potential solutions you have considered.

Feature Requests

We would love to hear from you about new features which would improve this app and further the aims of our project. Please provide as much detail and information as possible to show us why you think your new feature should be implemented.

Pull Requests

If you have developed a patch, bug fix, or new feature that would improve this app, please submit a pull request. It is best to communicate your ideas with the developers first before investing a great deal of time into a pull request to ensure that it will mesh smoothly with the project.

Remember that this project is licensed under the MIT license, and by submitting a pull request, you agree that your work will be, too.

Pull Request Guidelines

Ensure any install or build dependencies are removed before the end of the layer when doing a build.
Update the README.md with details of changes to the interface, including new plist variables, exposed ports, useful file locations and container parameters.
Ensure that your code conforms to our existing code conventions and test coverage.
Include the relevant issue number, if applicable.
You may merge the Pull Request in once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you.

Attribution

These contribution guidelines have been adapted from this good-Contributing.md-template.

Documentation

See 📱💻🖱Frontend Documentation for details on the frontend of our project. See 🔬⚗️🧪Data Science Documentation for details on the data science of our project.

This is a placeholder edit, in order to merge with master and trigger a coverage test.

Name		Name	Last commit message	Last commit date
Latest commit History 508 Commits
.github/workflows		.github/workflows
api		api
auth		auth
config		config
database		database
models		models
routers		routers
test		test
.codeclimate.yml		.codeclimate.yml
.gitignore		.gitignore
LICENSE		LICENSE
RC 3 plans.md		RC 3 plans.md
README.md		README.md
code_of_conduct.md		code_of_conduct.md
index.js		index.js
knexfile.js		knexfile.js
package-lock.json		package-lock.json
package.json		package.json
password -reset-outline.md		password -reset-outline.md
pull_request_template.md		pull_request_template.md

License

BloomTech-Labs/betterreads-be

Folders and files

Latest commit

History

Repository files navigation

API Documentation

1️⃣ Backend deployed at AWS_ELASTIC_BEANSTALK

1️⃣ Getting started

Seeding for tests

Express

2️⃣ Endpoints

User Authentication Routes

Body Required

Returns

Body Required

Returns

Authentication has been updated from sessions to more secure JSON web tokens. Here is what you need to do to ustilize them

Set up axioswithauth()

Required Body

Returns

Body Requires

Returns

Use Local Storage

Protected Routes

User Genres

Body Required

Returned

Body Required

Returned

Search Google Books, Search in our Books Table, and Post to our Books Table

Body Required

User Library

Body (All required)

Body Required

Body Required

Returns

User's shelves

Body Required for POST

Body Required

User's books on a shelf

Body Required

Recommendations

Returns

Requires

Returns

Reading Statistics

Returns

Returns

Book Tagging

Body Required

Returns

Returns

Returns

Body Required

Returns

Body Returned

Data Model

2️⃣ USERS

2️⃣ GENRES

2️⃣ USERGENRE

2️⃣ BOOKS

2️⃣ USERBOOKS

2️⃣ USERSHELVES

2️⃣ USERBOOKSONASHELF

2️⃣ Actions

Users

Books

UserBooks

UserShelves

UserBooksOnAShelf

AllUserData

3️⃣ Environment Variables

Contributing

👾 Issue/Bug Request 👾

Feature Requests

Pull Requests

Pull Request Guidelines

Attribution

Documentation

Packages