Responsible for provide data to the web
and mobile
front-ends. Permit to register NGOs and manage its incidents. The app has rate limit, brute force prevention, pagination, pagination's link header (to previous, next, first and last page), friendly errors, use JWT to logins, validation, also a simple versioning was made.
Easy peasy lemon squeezy:
$ yarn
Or:
$ npm install
Was installed and configured the
eslint
andprettier
to keep the code clean and patterned.
The application uses just one database: SQLite. For the fastest setup is recommended to use docker-compose, you just need to up all services:
$ docker-compose up -d
Store the NGOs and its incidents. For more information to how to setup your database see:
You can find the application's
knexfile.js
file in the root folder. It already comes withtest
anddevelopment
connection configured, so you will update it only when deploying or staging!
Remember to run the SQLite database migrations:
$ npx knex migrate:latest
See more information on Knex Migrations.
In this file you may configure your JWT settings, the environment, app's port and 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_PORT | Port number where the app will run. | 3333 |
NODE_ENV | App environment. The knex's connection configuration used rely on this key value, so if the environment is development the knex connection used will be development . |
development |
JWT_SECRET | A alphanumeric random string. Used to create signed tokens. | - |
JWT_EXPIRATION_TIME | How long time will be the token valid. See jsonwebtoken repo for more information. | 7d |
DOCS_URL | An url to docs where users can find more information about the app's internal code errors. | https://github.com/DiegoVictor/bethehero-api#errors-reference |
To start up the app run:
$ yarn dev:server
Or:
npm run dev:server
Instead of only throw a simple message and HTTP Status Code this API return friendly errors:
{
"statusCode": 429,
"error": "Too Many Requests",
"message": "Too Many Requests",
"code": 449,
"docs": "https://github.com/DiegoVictor/bethehero-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 errorscode
description.
code | message | description |
---|---|---|
141 | This incident is not owned by your NGO | The referenced incident is from another NGO. |
144 | Incident not found | The id sent not references an existing incident in the database. |
240 | Your NGO was not found | The NGO id sent through the login does not references an existing NGO in the database. |
244 | NGO not found | The id sent does not references an existing NGO in the database. |
340 | Token not provided | The JWT token was not sent. |
341 | Token invalid | The JWT token provided is invalid or expired. |
449 | Too Many Requests | You reached at the requests limit. |
All the routes with pagination returns 5 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 incidents:
GET http:https://localhost:3333/v1/incidents?page=3
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:https://localhost:3333/v1/incidents?page=7>; rel="last",
<http:https://localhost:3333/v1/incidents?page=4>; rel="next",
<http:https://localhost:3333/v1/incidents?page=1>; rel="first",
<http:https://localhost:3333/v1/incidents?page=2>; rel="prev"
See more about this header in this MDN doc: Link - HTTP.
Another header returned in routes with pagination, this bring the total records amount.
A few routes expect a Bearer Token in an Authorization
header.
You can see these routes in the routes section.
GET http:https://localhost:3333/v1/ngos/e5a76988/incidents?page=1 Authorization: Bearer <token>
To achieve this token you just need authenticate through the
/sessions
route and it will return thetoken
key with a valid Bearer Token.
A simple versioning was made. Just remember to set after the host
the /v1/
string to your requests.
GET http:https://localhost:3333/v1/ngos
route | HTTP Method | pagination | params | description | auth method |
---|---|---|---|---|---|
/sessions |
POST | ❌ | Body with NGO id . |
Authenticates user, return a Bearer Token and ngo's id and name. | ❌ |
/ngos |
GET | ✔️ | page query parameter. |
Lists NGOs. | ❌ |
/ngos/:id |
GET | ❌ | :id of the NGO. |
Return one NGO. | ❌ |
/ngos |
POST | ❌ | Body with new NGO data. | Create a new NGO. | ❌ |
/incidents |
GET | ✔️ | page query parameter. |
List incidents. | ❌ |
/incidents/:id |
GET | ❌ | :id of the incident. |
Return one incident. | ❌ |
/incidents |
POST | ❌ | Body with new incident data. | Create new incidents. | Bearer |
/incidents/:id |
DELETE | ❌ | :id of the incident. |
Remove an incident. | Bearer |
/ngos/:ngo_id/incidents |
GET | ✔️ | page query parameter and :ngo_id of the NGO. |
List NGO's incidents. | ❌ |
Routes with
Bearer
as auth method expect anAuthorization
header. See Bearer Token section for more information.
POST /session
Request body:
{
"id": "e5a76988"
}
POST /ngos
Request body:
{
"name": "Doe and Sons",
"email": "[email protected]",
"whatsapp": "39379976591",
"city": "Corinefurt",
"uf": "NE"
}
POST /incidents
Request body:
{
"title": "Forward Tactics Representative",
"description": "Adipisci non assumenda ad sequi.",
"value": 512.93
}
Jest was the choice to test the app, to run:
$ yarn test
Or:
$ npm run test
You can see the coverage report inside tests/coverage
. They are automatically created after the tests run.