Coletaí API ♻️

Description

Coletaí's main objective is to bring recycling cooperatives closer to people who sort recyclable waste at home.

Registered users can request collections from the cooperatives, which in turn have the option of accepting or not the requests.

The cooperative, after carrying out the collection, registers on the system that the request has been completed.

Both users and cooperatives can track the progress and status of collection requests.

Table of Contents

• Coletaí API ♻️

  • Description

  • Table of Contents

  • Built With

  • API Reference

    • Endpoints

      • USERS
        • User Registration
          • Request
          • Response
        • User Sign In
          • Request
          • Response
      • COOPERATIVES
        • Cooperative Registration
          • Request
          • Response
        • Cooperative Sign In
          • Request
          • Response
        • List all Cooperatives names and location
          • Response
      • COLLECTIONS
        • Create Collection
          • Request
          • Response
        • List Collections by User
          • Response
        • List Collections by Cooperative
          • Response
        • Cancel Collection
          • Response
        • Finish Collection
          • Response
      • ERROR NOTES

  • Running the Project

  • Testing the API

    • Endpoints (Thunder Client)
    • Jest
      • Unit tests
      • Integration tests

Built With

API Reference

USERS

User Registration

POST /users

Request

Body	Type	Description
name	string	Required
email	string	Required, must be unique and a valid email format
password	string	Required
latitude	number	Required, must be a valid latitude
longitude	number	Required, must be a valid longitude

{
  "name": "Example",
  "email": "[email protected]",
  "password": "pass123",
  "latitude": -50,
  "longitude": -90
}

Response

Body	Code	Description
empty	201	Created
json	409	Conflict, email is already being used
json	422	Unprocessable Entity, request body is invalid

User Sign In

POST /users/sign-in

Request

Body	Type	Description
email	string	Required, must be a valid email format
password	string	Required

{
  "email": "[email protected]",
  "password": "pass123",
}

Response

Body	Code	Description
json	200	OK, returns a token
json	401	Unauthorized, incorrect password
json	404	Not Found, user does not exist
json	422	Unprocessable Entity, request body is invalid

{
  "token": "JWT token"
}

COOPERATIVES

Cooperative Registration

POST /cooperatives

Request

Body	Type	Description
name	string	Required, must be unique
email	string	Required, must be unique and a valid email format
password	string	Required
latitude	number	Required, must be a valid latitude
longitude	number	Required, must be a valid longitude

{
  "name": "Example",
  "email": "[email protected]",
  "password": "pass123",
  "latitude": -50,
  "longitude": -90
}

Response

Body	Code	Description
empty	201	Created
json	409	Conflict, email or name is already being used
json	422	Unprocessable Entity, request body is invalid

Cooperative Sign In

POST /cooperatives/sign-in

Request

Body	Type	Description
email	string	Required, must be a valid email format
password	string	Required

{
  "email": "[email protected]",
  "password": "pass123",
}

Response

Body	Code	Description
json	200	OK, returns a token
json	401	Unauthorized, incorrect password
json	404	Not Found, user does not exist
json	422	Unprocessable Entity, request body is invalid

{
  "token": "JWT token"
}

List all Cooperatives names and location

GET /cooperatives/name-location

Response

Body	Code	Description
json	200	OK, returns an array

[
  {
    "name": "Example",
    "longitude": -90,
    "latitude": -50
  },
  {
    "name": "Example 2",
    "longitude": -90,
    "latitude": -50
  }
]

COLLECTIONS

• Every /collections route is authenticated using Bearer TOKEN;
• Only USERS are able to create collections;
• Only COOPERATIVES are able to cancel or finish a collection;
• The user token must be sent in the Authorization request header;
• The API will return the following errors if the authentication fails:

Code	Description
401	Unauthorized, invalid token
400	Bad Request, token was not sent
422	Unprocessable Entity, token is not in the Bearer format

Create Collection

POST /collections

Request

There are only four valid recycling types:

• "Plástico";
• "Metal";
• "Vidro";
• "Papel";

Body	Type	Description
types	array	Required, must have at least one type
description	string	Required, must be a maximum of 140 characters

{
  "types": [
    {
      "name": "Metal"
    }
  ],
  "description": "Random description"
}

Response

Body	Code	Description
empty	201	Created
json	404	Not Found, the recycling type does not exist
json	422	Unprocessable Entity, request body is invalid

List Collections by User

GET /collections/user

Response

Body	Code	Description
json	200	OK

[
  {
    "id": "c0e27d49-4f2f-49c3-a985-4f13e9bb7a2c",
    "description": "Random description",
    "status": "ongoing",
    "created_at": "2022-10-10T15:15:54.374Z",
    "updated_at": "2022-10-10T15:15:54.375Z",
    "cooperative": {
      "id": "4142c078-12b3-4a51-88b1-0211167bba40",
      "name": "Random"
    },
    "user": {
      "id": "2d298149-014b-4b1d-90bd-abf9a77fa942",
      "name": "Random",
      "address": "user address"
    },
    "types": [
      {
        "name": "Metal"
      }
    ]
  },
  {
    "id": "c344936a-a015-446d-95ac-9aca2cf1a5d5",
    "description": "Random description",
    "status": "ongoing",
    "created_at": "2022-10-10T15:15:52.978Z",
    "updated_at": "2022-10-10T15:15:52.979Z",
    "cooperative": {
      "id": "4142c078-12b3-4a51-88b1-0211167bba40",
      "name": "Random"
    },
    "user": {
      "id": "2d298149-014b-4b1d-90bd-abf9a77fa942",
      "name": "Random",
      "address": "user address"
    },
    "types": [
      {
        "name": "Metal"
      }
    ]
  }
]

List Collections by Cooperative

GET /collections/cooperative

Response

Body	Code	Description
json	200	OK

[
  {
    "id": "c0e27d49-4f2f-49c3-a985-4f13e9bb7a2c",
    "description": "Random description",
    "status": "ongoing",
    "created_at": "2022-10-10T15:15:54.374Z",
    "updated_at": "2022-10-10T15:15:54.375Z",
    "cooperative": {
      "id": "4142c078-12b3-4a51-88b1-0211167bba40",
      "name": "Random"
    },
    "user": {
      "id": "2d298149-014b-4b1d-90bd-abf9a77fa942",
      "name": "Random",
      "address": "user address"
    },
    "types": [
      {
        "name": "Metal"
      }
    ]
  },
  {
    "id": "c344936a-a015-446d-95ac-9aca2cf1a5d5",
    "description": "Random description",
    "status": "ongoing",
    "created_at": "2022-10-10T15:15:52.978Z",
    "updated_at": "2022-10-10T15:15:52.979Z",
    "cooperative": {
      "id": "4142c078-12b3-4a51-88b1-0211167bba40",
      "name": "Random"
    },
    "user": {
      "id": "2d298149-014b-4b1d-90bd-abf9a77fa942",
      "name": "Random",
      "address": "user address"
    },
    "types": [
      {
        "name": "Metal"
      }
    ]
  }
]

Cancel Collection

POST /collections/{id}/cancel

Response

Body	Code	Description
empty	200	OK
json	404	Not Found, collection not found
json	403	Forbidden, the collection does not belong to the cooperative
json	400	Bad Request, the collection is already cancelled or finished

Finish Collection

POST /collections/{id}/finish

Response

Body	Code	Description
empty	200	OK
json	404	Not Found, collection not found
json	403	Forbidden, the collection does not belong to the cooperative
json	400	Bad Request, the collection is already cancelled or finished

ERROR NOTES

When a request returns an error, the response is a json:

{
  "name": "Error Name",
  "message": "Error Details"
}

Running the Project

1. Clone the repository:

   git clone https://github.com/akiraTatesawa/coletai-back.git

2. Navigate to the project directory:

   cd coletai-back/

3. Install the dependencies:

   npm install

4. Set your environment variables following the .env.sample file:

   Name	Type
   DATABASE_URL	string
   PORT	number
   JWT_SECRET	string

    PORT=
    DATABASE_URL=
    JWT_SECRET=

5. Run the migrations script:

   npm run migrate

6. Run the project on dev mode:

   npm run dev

Testing the API

Endpoints (Thunder Client)

1. Import the collection and environments on the thunder_client/ directory;
2. Set the URL environment variable on the Thunder Client DEV env;
3. Go to the Coletaí collection and you are ready to use the API!

Jest

1. Create a .env.test file on the root of the project;

2. Set the DATABASE_URL and JWT_SECRET variables;

3. Run the script:

   npm run test

   This will execute the unit and integration tests all at once

Unit tests

Run the script

   npm run test:unit

Integration tests

Run the script

   npm run test:int