The Bookstore API Endpoint Specifications

Our Product Manager has just announced to everyone in a zoom meeting that we will be starting a new project.

This new product is going to be a classified listings website focused on book exchange whereby people can post used books for sale and have the ability to view public book listings if they want to buy.

Let's call this new application: trademebooks (tmb for short).

Our Product Manager has already had the Designer spin up the finalized wireframes for the project. The frontend and backend Tech Leads have already aligned, and have finalized the details of the backend RESTful API endpoints that we will be building.

Below are all the RESTful endpoints we will be building for our new Bookstore API.

API Endpoint #1: User Registration

We'll need a way for users to register for an account with our API. We'll need to collect a public user's first name, last name, email, password, and phone number and store them in the database of our application.

We'll need to provide some level of form validation for all those user inputs. All the fields are required, of course the email and phone number should all be in the correct format. In additional, we'll need the user to type his password a second time to make sure there is some sort of password confirmation.

Remember, there can only be one email registered to one user account, so there must also be some sort of check on our backend to make sure an email is not already taken.

Last but not least, if the registration does go through, we want to send the user an email letting them know that they have successfully registered on our website.

A user can login to our application with an email and password.

Like most authentication system, there will be some sort of validation on both the frontend backend side. For the frontend side, it's quite simple, both fields are required. For the backend side, a user must exist in the database along with the correctly entered password.

If both the frontend and backend validation both pass, then we will log the user into the application and persist a login session.

API Endpoint #3: User Logout

~~Logging a user out of a session is quite simple since there are no inputs. If there is a currently authenticated user, then we will destroy that session. If not, then we don't do anything.~~

Update: our Product has realized that we are in too much of a rush to implement the logout feature. Maybe we'll have more bandwidth in the future 😄.

API Endpoint #4: Get Authenticated User

We'll need some sort of way for the frontend team to get the currently authenticated user's profile. We'll need an endpoint to output their first name, last name, and email. If there is no currently authenticated user, then we won't return a user.

API Endpoint #5: Retrieve all Book Listings

Now comes the book listings part. The frontend team and design team have decided that they want the front page to display all the books on our website from the most recently added listings to the oldest listings.

Each book listing will have an ID, userId, title, description, price, author, published date, and date added field.

Note that the ID is for the book and the userId is used to identify the owner who posted that book.

API Endpoint #6: Retrieve a Book Listing

Retrieving a single book will be very similar to the retrieval of all books, except we will need to provide a specified book ID when calling our API endpoint. If the book listing is not found, then we will let the user know.

Like before, the specified book listing will have an ID, userId, title, description, price, author, published date, and date added field.

API Endpoint #7: Create a Book Listing

For a user to create a listing, they must first be logged into the application, otherwise they will not be able to access this endpoint.

In order to create a book listing, the title, description, price, author, published date fields are all required and must be in alphanumeric format, except for the price field which will be any number up to 2 decimal places and the published date field which will be of any valid date format.

API Endpoint #8: Update a Book Listing

For a user to update an existing book, the user must first know the ID of the book. The user also must be logged in as well be the owner or the creator of that book.

If a book with a specified ID does not exist, then we'll let the user know that we can't update it since it is not in our database.

If a user tries to update a book in which he is not the creator of, then we'll let them know that they do not have sufficient permissions.

API Endpoint #9: Delete a Book Listing

For a user to delete an existing book, it is very similar to updating a book. The user must know the ID of the book, the user must be logged in as well as be the owner or the creator of that book.

If a book with a specified ID does not exist, then we'll let the user know that we can't delete it since it's not in our database.