Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/diegovictor/cargo-terminal-api
Manage travels' origins and destinations, drivers and vehicles' models and types
https://github.com/diegovictor/cargo-terminal-api
Last synced: 2 months ago
JSON representation
Manage travels' origins and destinations, drivers and vehicles' models and types
- Host: GitHub
- URL: https://github.com/diegovictor/cargo-terminal-api
- Owner: DiegoVictor
- License: mit
- Created: 2021-05-21T00:25:21.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-16T12:15:24.000Z (3 months ago)
- Last Synced: 2024-10-18T06:04:58.504Z (3 months ago)
- Language: JavaScript
- Homepage:
- Size: 667 KB
- Stars: 2
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# [API] Cargo Terminal
[](https://ci.appveyor.com/project/DiegoVictor/cargo-terminal-api)
[](https://www.mongodb.com/)
[](https://nodemon.io/)
[](https://eslint.org/)
[](https://github.com/airbnb/javascript)
[](https://jestjs.io/)
[](https://codecov.io/gh/DiegoVictor/cargo-terminal-api)
[](https://raw.githubusercontent.com/DiegoVictor/cargo-terminal-api/main/LICENSE)
[](http://makeapullrequest.com)
[](https://insomnia.rest/run/?label=Cargo%20Terminal&uri=https%3A%2F%2Fraw.githubusercontent.com%2FDiegoVictor%2Fcargo-terminal-api%2Fmaster%2FInsomnia_2024-06-21.json)
Responsible for provide data to the [`web`](https://github.com/DiegoVictor/cargo-terminal-web) version. Permit to register vehicles, drivers, arrivals and allows to retrieve an aggregation of travels. The app has pagination, pagination's link header (to previous, next, first and last page), friendly errors, validation, also a simple versioning was made.
## Table of Contents
* [Installing](#installing)
* [Configuring](#configuring)
* [MongoDB](#mongodb)
* [.env](#env)
* [Usage](#usage)
* [Error Handling](#error-handling)
* [Errors Reference](#errors-reference)
* [Pagination](#pagination)
* [Link Header](#link-header)
* [X-Total-Count](#x-total-count)
* [Versioning](#versioning)
* [Routes](#routes)
* [Requests](#requests)
* [Running the tests](#running-the-tests)
* [Coverage report](#coverage-report)
# Installing
Easy peasy lemon squeezy:
```
$ yarn
```
Or:
```
$ npm install
```
> Was installed and configured the [`eslint`](https://eslint.org/) and [`prettier`](https://prettier.io/) to keep the code clean and patterned.
## Configuring
The application use just one database: [MongoDB](https://www.mongodb.com). For the fastest setup is recommended to use [docker-compose](https://docs.docker.com/compose/), you just need to up all services:
```
$ docker-compose up -d
```
### MongoDB
Store all application data. 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 cargo-terminal-mongo -d -p 27017:27017 mongo
```
### .env
In this file you may configure your MongoDB connection url, app's port and a url to documentation (this will be returned with error responses, see [error section](#error-handling)). 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`
|MONGO_HOST|MongoDB's host.|`mongodb`
|MONGO_PORT|MongoDB's port.|`27017`
|MONGO_DB|Database name.|`cargo-terminal`
|DOCS_URL|An url to docs where users can find more information about the app's internal code errors.|`https://github.com/DiegoVictor/cargo-terminal-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:
```json
{
"statusCode": 404,
"error": "Not Found",
"message": "Arrival not found",
"code": 146,
"docs": "https://github.com/DiegoVictor/devradar-api#errors-reference"
}
```
> Errors are implemented with [@hapi/boom](https://github.com/hapijs/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](#errors-reference)) you can see the errors `code` description.
### Errors Reference
|code|message|description
|---|---|---
|144|Vehicle not found|The `id` sent not references an existing vehicle in the database while creating an arrival.
|145|Driver not found|The `id` sent not references an existing driver in the database while creating an arrival.
|146|Arrival not found|The `id` sent not references an existing arrival in the database while trying to update an arrival.
|147|Vehicle not found|The `id` sent not references an existing vehicle in the database while trying to update an arrival.
|148|Driver not found|The `id` sent not references an existing driver in the database while trying to update an arrival.
|244|Vehicle not found|The `id` sent not references an existing vehicle in the database while creating a driver.
|245|Driver not found|The `id` sent not references an existing driver in the database while trying to update a driver.
|246|Vehicle not found|The `id` sent not references an existing vehicle in the database while trying to update a driver.
|344|Vehicle not found|The `id` sent not references an existing vehicle in the database while trying to update a vehicle.
## Pagination
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://localhost:3333/v1/arrivals?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.
```
; rel="last",
; rel="next",
; rel="first",
; rel="prev"
```
> See more about this header in this MDN doc: [Link - HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Link).
### X-Total-Count
Another header returned in routes with pagination, this bring the total records amount.
## Versioning
A simple versioning was made. Just remember to set after the `host` the `/v1/` string to your requests.
```
GET http://localhost:3333/v1/arrivals
```
## Routes
|route|HTTP Method|pagination|params|description
|:---|:---:|:---:|:---:|:---:
|`/travels`|GET|:x:| - |Return an aggregation of travels (origins and destinations by type).
|`/vehicles`|GET|:heavy_check_mark:|`page` query parameter.|Lists cars.
|`/vehicles`|POST|:x:|Body with vehicle `type` and `model`.|Create a new car.
|`/vehicles/:id`|PUT|:x:|`:id` of the vehicle and body with vehicle `type` and `model`.|Update a car.
|`/drivers`|GET|:heavy_check_mark:|`page`, `active` and `vehicle` query parameter.|Lists drivers.
|`/drivers`|POST|:x:|Body with driver `cpf`, `name`, `phone`, `birthday`, `gender`, `cnh_number`, `cnh_type` and `vehicle_id`.|Create a new driver.
|`/drivers/:id`|PUT|:x:|`:id` of the driver and body with driver `cpf`, `name`, `phone`, `birthday`, `gender`, `cnh_number`, `cnh_type` and `vehicle_id`.|Update a driver.
|`/arrivals`|GET|:heavy_check_mark:|`page`, `filled`, `date_start` and `date_end` query parameter.|Lists arrivals.
|`/arrivals`|POST|:x:|Body with arrival `vehicle_id`, `driver_id`, `origin.latitude`, `origin.longitude`, `destination.latitude` and `destination.longitude`.|Create a new arrival.
|`/arrivals/:id`|PUT|:x:|`:id` of the driver and body with arrival `vehicle_id`, `driver_id`, `origin.latitude`, `origin.longitude`, `destination.latitude` and `destination.longitude`.|Update an arrival.
### Requests
* `POST /vehicles`
Request body:
```json
{
"type": 2,
"model": "Camry"
}
```
* `PUT /vehicles/:id`
Request body:
```json
{
"type": 1,
"model": "Land Cruiser"
}
```
* `POST /drivers`
Request body:
```json
{
"cpf": "99999999999",
"name": "John Doe",
"phone": "+55 679 924356443",
"birthday": "2000-01-01",
"gender": "M",
"cnh_number": "DJUKPTRF9EH178332",
"cnh_type": "A",
"vehicle_id": "60bbb21dd63cfd06c06cd3b8"
}
```
* `PUT /drivers/:id`
Request body:
```json
{
"cpf": "99999999999",
"name": "Jane Doe",
"phone": "+55 679 924356443",
"birthday": "1993-01-01",
"gender": "F",
"cnh_number": "KIENSTQF3EH179102",
"cnh_type": "B",
"vehicle_id": "60bbb1c4d63cfd06c06cd3b2"
}
```
* `POST /arrivals`
Request body:
```json
{
"vehicle_id": "60bbb1c4d63cfd06c06cd3b2",
"driver_id": "60bbb289d63cfd06c06cd3b9",
"origin": {
"longitude": -145.6955,
"latitude": 16.3805
},
"destination": {
"longitude": -100.6317,
"latitude": 60.1977
}
}
```
* `PUT /arrivals/:id`
Request body:
```json
{
"filled": true,
"vehicle_id": "60bbb1c4d63cfd06c06cd3b2",
"driver_id": "60bbb289d63cfd06c06cd3b9",
"origin": {
"longitude": -100.6317,
"latitude": 60.1977
},
"destination": {
"longitude": -145.6955,
"latitude": 16.3805
}
}
```
# Running the tests
[Jest](https://jestjs.io/) 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.