[API] GoBarber

Responsible for provide data to the web and mobile front-ends. Permit to register yourself as a provider or a customer, allows customers to see providers free days' hours availability and book with them a barber shop service and also notify by email providers when a book is created. Also the app has rate limit, uses JWT to logins and validation.

Table of Contents

• Installing
  • Configuring
    • Postgres
      • Migrations
    • MongoDB
    • Redis
    • .env
    • Rate Limit (Optional)
• Usage
  • Pagination
    • Link Header
    • X-Total-Count
  • Bearer Token
  • Routes
    • Requests
• Running the tests
  • Coverage report

Installing

Easy peasy lemon squeezy:

$ yarn

Or:

$ npm install

Was installed and configured the eslint and prettier to keep the code clean and patterned.

Configuring

The application use three databases: Postgres, MongoDB and Redis. For the fastest setup is recommended to use docker-compose, you just need to up all services:

$ docker-compose up -d

Postgres

Responsible to store almost all application data. If for any reason you would like to create a Postgres container instead of use docker-compose, you can do it by running the following command:

$ docker run --name gobarber-postgres -e POSTGRES_PASSWORD=docker -p 5432:5432 -d postgres

Migrations

Remember to run the database migrations:

$ yarn ts-node-dev ./node_modules/typeorm/cli.js migration:run

Or:

$ yarn typeorm migration:run

See more information on TypeORM Migrations.

MongoDB

Store application's notifications. If for any reason you would like to create a MongoDB container instead of use docker-compose, you can do it by running the following command:

$ docker run --name gobarber-mongo -d -p 27017:27017 mongo

Redis

Responsible to store data utilized by the rate limit middleware and the application's cache. If for any reason you would like to create a MongoDB container instead of use docker-compose, you can do it by running the following command:

$ docker run --name gobarber-redis -d -p 6379:6379 redis:alpine

.env

In this file you may configure your Postgres, MongoDB and Redis database connection, JWT settings, email and storage driver and app's urls. Rename the .env.example in the root directory to .env then just update with your settings.

key	description	default
APP_API_URL	Used to mount avatars' urls.	http://127.0.0.1:3333
APP_WEB_URL	Used to create the reset password link (front-end) sent in the recover password email.	http://127.0.0.1:3000
APP_SECRET	A alphanumeric random string. Used to create signed tokens.	-
MAIL_DRIVER	Indicate what email service use to send messages, the possible values are ethereal and ses, to use the SES service remember to to configure the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_DEFAULT_REGION keys.	ethereal
AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY	These keys are necessary to AWS allow the application to use the S3 and SES services throught API. See how to get yours keys here: Set up AWS Credentials	-
AWS_DEFAULT_REGION	You can see your default region in the navigation bar at the top right after login in the AWS Management Console. Read AWS service endpoints to know more about regions.	-
AWS_S3_BUCKET_NAME	Amazon S3 stores data as objects within buckets. To create a bucket see Creating a bucket	gobarber
POSTGRES_HOST	Postgres host.	pg
POSTGRES_PORT	Postgres port.	5432
POSTGRES_USERNAME	Postgres user.	postgres
POSTGRES_PASSWORD	Postgres password.	-
POSTGRES_DATABASE	Application's database name.	gobarber
MONGO_HOST	MongoDB host.	mongo
MONGO_PORT	MongoDB port.	27017
MONGO_DATABASE	MongoDB database name.	gobarber
REDIS_HOST	Redis host.	redis
REDIS_PORT	Redis port.	6379
REDIS_PASSWORD	Redis password.	-
STORAGE_DRIVER	Indicate where the users's avatar will be stored, the possible values are disk and s3, to store into S3 remember to configure all the AWS_* keys.	disk

Rate Limit (Optional)

The project comes pre-configured, but you can adjust it as your needs.

• src/config/rate_limit.ts

key	description	default
duration	Number of seconds before consumed points are reset.	300
points	Maximum number of points can be consumed over duration.	10

The lib rate-limiter-flexible was used to rate the api's limits, for more configuration information go to Options page.

Usage

To start up the app run:

$ yarn dev:server

Or:

npm run dev:server

Pagination

All the routes with pagination returns 30 records per page, to navigate to other pages just send the page query parameter with the number of the page.

• To get the third page of providers:

GET http://localhost:3333/providers?page=3

Link Header

Also in the headers of every route with pagination the Link header is returned with links to first, last, next and prev (previous) page.

<http://localhost:3333/providers?page=7>; rel="last",
<http://localhost:3333/providers?page=4>; rel="next",
<http://localhost:3333/providers?page=1>; rel="first",
<http://localhost:3333/providers?page=2>; rel="prev"

See more about this header in this MDN doc: Link - HTTP.

X-Total-Count

Another header returned in routes with pagination, this bring the total records amount.

Bearer Token

A few routes expect a Bearer Token in an Authorization header.

You can see these routes in the routes section.

POST http://localhost:3333/appointments Authorization: Bearer <token>

To achieve this token you just need authenticate through the /sessions route and it will return the token key with a valid Bearer Token.

Routes

route	HTTP Method	pagination	params	description	auth method
/sessions	POST	❌	Body with user's email and password.	Authenticates user, return a Bearer Token and user's id and email.	❌
/users	POST	❌	Body with user's email and password.	Create new users.	❌
/profile	GET	❌	-	Logged in user profile.	Bearer
/profile	PUT	❌	Body with user name, email, old_password, password and password_confirmation.	Update user.	Bearer
/users/avatar	PATCH	❌	Multipart payload with a avatar field with a image (See insomnia file for good example).	Update user avatar.	Bearer
/appointments	POST	❌	Body with appointment provider_id and date.	Create a new appointment.	Bearer
/appointments/schedule	GET	❌	day, month and year query parameters.	Return user's scheduled appointments in a specific date.	Bearer
/providers	GET	✔️	page query parameter.	Lists providers.	Bearer
/providers/:id/month_availability	GET	❌	month and year query parameters.	List month's days availability	Bearer
/providers/:id/day_availability	GET	❌	day, month and year query parameters.	List a specific day availability.	Bearer
/password/forgot	POST	❌	Body with user's email.	Send to user the reset password email.	❌
/password/reset	POST	❌	Body with user's new password and password_confirmation.	Reset user's password.	❌

Routes with Bearer as auth method expect an Authorization header. See Bearer Token section for more information.

Requests

• POST /session

Request body:

{
  "email": "johndoe@example.com",
  "password": "123456"
}

• POST /users

Request body:

{
  "name": "John Doe",
  "email": "johndoe@example.com",
  "password": "123456"
}

• PUT /profile

Request body:

{
  "name": "John Doe",
  "email": "johndoe@example.com",
  "old_password": "123456",
  "password": "123456789",
  "password_confirmation": "123456789"
}

• PATCH /users/avatar

Image file

• POST /appointments

Request body:

{
  "provider_id": "01931fee-32d4-4af7-b4e9-12159c5d703e",
  "date": "2020-11-20 15:00:00"
}

• POST /password/forgot

Request body:

{
  "email": "johndoe@example.com"
}

• POST /password/reset

Request body:

{
  "password": "123456",
  "password_confirmation": "123456",
  "token": "6878f9b2-eb7c-4ad6-ac72-66d958f117c2"
}

Running the tests

Jest was the choice to test the app, to run:

$ yarn test

Or:

$ npm run test

Coverage report

You can see the coverage report inside test/coverage. They are automatically created after the tests run.