Logging the User In - Planning

Refer back to Chapter 6, The Bookstore API Endpoint Specifications, API Endpoint #2: User Login section for the API endpoint specifications.

1 - Route Name

For logging the user into our application, I propose the following URI.

POST /api/v1/auth/login

Now if you've been paying close attention, you'll notice that we've been following the guidelines from chapter 6, Method Verbs and URI Design very closely.

In this particular case, two questions come to mind.

1. We are not creating a resource, so which method verb should we use?

2. For the URI, Guideline #4: Avoid actions and verbs in the URI in chapter 3, URI Design, URI Path Design tells us that we should not use verbs in our URI, in this case, we are using "login".

To answer the first question, it's simple, we can use either POST or PUT. As long as the method verb we are using has some sort of way for us to pass a payload to the server. In terms of semantics, I would argue either is fine, both can be used.

As for the second question, the guideline is to avoid action verbs. In this case, we will be pragmatic, but also follow the rule of thumb, which is to use an action verb only when a URI does not adhere to a CRUD operation. In our case a login action does not creating any new resource, therefore it is fine to put that in our URI.

2 - Input Request

As stated from the endpoint specifications in the previous chapter, we will accept the following input fields from the client.

• email

• password

3 - Middleware

Since the user doesn't need to be logged in, we can leave the middleware part out.

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.

• email - required, must be a valid email format.

• password - required, at least 6 characters.

5 - Domain

Since we already created the userModel, we'll just be building on top of that.

First, we'll need some sort of way to do a check in our database on whether or not a row exists with the given email and password.

userRepository

• findUserByEmailAndPassword()

Then, we'll have some sort of authService to call the findUserByEmailAndPassword() in userRepository. We'll fit this in a loginUser function.

Don't forget, we'll need to check weather the credentials are valid or not based on findUserByEmailAndPassword().

authService

• loginUser()

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

There are no events based on the specifications in the previous chapter.

7 - Response

There are 3 possible responses that we can output from this API.

The first is from the form validation.

{
  "status": "error",
  "code": 400,
  "message": "There were errors with the validation",
  "data": null,
  "errors": ["The email format is invalid."]
}

The second is when we do a check from our authService seeing if we could find a possible row in the database with a given pair of email and password.

{
  "status": "error",
  "code": 400,
  "message": "Invalid credentials, please try a different email and password combination.",
  "data": null,
  "errors": [
    "Invalid credentials, please try a different email and password combination."
  ]
}

The third is if all validation passes, we'll log the user in and output the user in a success response.

{
  "status": "success",
  "code": 200,
  "message": "The user has successfully logged in.",
  "data": {
    "id": "61f888043b95e61830a98da0",
    "first_name": "Yichen",
    "last_name": "Zhu",
    "email": "[e-mail]",
    "phone_number": "1234567890"
  },
  "errors": null
}