Creating A Book Listing - Planning

Refer back to Chapter 6, The Bookstore API Endpoint Specifications, API Endpoint #7: Create a Book Listing section for the API endpoint specifications.

1 - Route Name

Referring back to the sections under chapter 3, Method Verbs and URI Design, we can continue to build upon our books namespace. In fact we'll be using that for the rest of the chapter.

We'll use POST as our method verb of choice since we are creating a resource, and this is what we'll be sticking with as our route name.

POST /api/v1/books

2 - Input Request

From the specifications, these are the fields that will be input to us by the user.

• title

• description

• price

• author

• datePublished

3 - Middleware

This middleware part of this feature will be quite simple. Recall in the previous chapter, when we went over the section Getting Authenticated User - Implementation. We built ourselves a nice little helper that will let us guard against requests from users who are not authenticated in our application. We'll be reusing that middleware for this feature and for the rest of the remaining sections of this chapter.

4 - Validation

From the looks of the specification, it would seem like we will need to perform the following validation rules for each of the fields.

• title - required.

• description - required.

• price - required, numeric, minimum number is 1.

• author - required.

• datePublished- required, valid date format.

5 - Domain

If you've been paying attention in the previous 2 chapters of the book, you'll probably guess what 3 files we are going to create.

From the specifications, it looks like we will need the following book entity in our domain layer.

bookModel

• title

• description

• price

• author

• datePublished

We'll also need some sort of way to make a query to the database to insert the book in, so we'll create a bookRepository layer with the method create() to do so.

bookRepository

• create()

On top of that, our controller will call a service to createBook(), in this case, it will be the bookService which will use the userRepository layer.

bookService

• createBook()

This is a rough outline of how we are going to be implementing these functions, we'll take a deeper dive at the implementations in the next section of this chapter.

6 - Events

None.

7 - Response

There are 3 possible responses that can be output with this endpoint.

The first is the authentication middleware that we'll be adding in.

{
  "status": "error",
  "code": 401,
  "message": "Access denied: you must be logged in to access this API endpoint.",
  "data": null,
  "errors": ["You must be logged in."]
}

The second has to deal with whether or not the client has put in the correct fields to pass the form validation.

{
  "status": "error",
  "code": 400,
  "message": "There were errors with the validation.",
  "data": null,
  "errors": ["The price must be at least 1.", "The author field is required."]
}

The third, of course, is the successful scenario.

{
  "status": "success",
  "code": 200,
  "message": "Book has successfully been added to the database.",
  "data": {
    "id": "620066e1f84bfd64e7125830",
    "title": "'Harry Potter and the Awesome Book of Nothing",
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
    "price": 100,
    "author": "J.K. Rowling",
    "datePublished": "December 25, 2010"
  },
  "errors": null
}