[API] Ecoleta

Responsible for provide data to the web and mobile front-ends. Allow to register points and set the items type that point receive. The app has friendly errors, validation, also a simple versioning was made.

Table of Contents

• Installing
  • Configuring
    • SQLite
      • Migrations
      • Seeds
    • .env
• Usage
  • Error Handling
    • Errors Reference
  • Versioning
  • 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 just one databases: SQLite. For the fastest setup is recommended to use docker-compose, you just need to up all services:

$ docker-compose up -d

SQLite

Store the points and point's items. For more information to how to setup your database see:

• knexfile.js

You can find the application's knexfile.js file in the root folder.

Migrations

Remember to run the SQLite database migrations:

$ npx knex migrate:latest --knexfile knexfile.ts

See more information on Knex Migrations.

Or simply:

$ yarn knex:migrate

Seeds

Also, remember to run the seeds, it will create some default items.

$ npx knex seed:run --knexfile knexfile.ts

Read more on Seed CLI

Or simply:

$ yarn knex:seed

.env

In this file you may configure your app's url and port, also a url to documentation (this will be returned with error responses, see error section). Rename the .env.example in the root directory to .env then just update with your settings.

key	description	default
APP_URL	App's url, when testing the mobile version on devices is strongly recommended to set this key to your Expo url (e.g. 192.168.0.6)	http://localhost
APP_PORT	Port number where the app will run.	3333
NODE_ENV	App environment.	development
DOCS_URL	An url to docs where users can find more information about the app's internal code errors.	https://github.com/DiegoVictor/ecoleta-api#errors-reference

Usage

To start up the app run:

$ yarn dev:server

Or:

$ npm run dev:server

Error Handling

Instead of only throw a simple message and HTTP Status Code this API return friendly errors:

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Point not found",
  "code": 144,
  "docs": "https://github.com/DiegoVictor/ecoleta-api#errors-reference"
}

Errors are implemented with @hapi/boom. As you can see a url to error docs are returned too. To configure this url update the DOCS_URL key from .env file. In the next sub section (Errors Reference) you can see the errors code description.

Errors Reference

code	message	description
144	Point not found	The id sent not references an existing point in the database.

Versioning

A simple versioning was made. Just remember to set after the host the /v1/ string to your requests.

GET http://localhost:3333/v1/points

Routes

route	HTTP Method	params	description
/items	GET	-	Lists points' items.
/points	GET	city, uf and items query parameters.	Lists points.
/points/:id	GET	:id of the point.	Return one point.
/points	POST	Body with new point form data (See insomnia file for good example).	Create a new point.

Requests

• POST /points

Request body:

{
  "name": "Hackett, Becker and Fadel",
  "email": "contact@hbfadel.com",
  "whatsapp": "+551540331438",
  "latitude": -85.8713,
  "longitude": -73.3957,
  "city": "São Paulo",
  "uf": "SP",
  "items": "1, 2"
  "image": <file>
}

• GET /points?city=Sao+Paulo&uf=SP&items=1,2

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 tests/coverage. They are automatically created after the tests run.