Skip to content

Commit 2802dcc

Browse files
JawherKlJawherKl
authored
Merge pull request #11 from JawherKl/feature/12-update-readme-file-content
update the readme file with that new feature implement
2 parents c5089ba + c553b2f commit 2802dcc

File tree

1 file changed

+140
-105
lines changed

1 file changed

+140
-105
lines changed

‎README.md

Lines changed: 140 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -1,130 +1,165 @@
11
# Node.js API with PostgreSQL
2-
![nodepost](https://github.com/user-attachments/assets/6f206c6e-dea0-4045-8baa-a04e74a5fbf8)
3-
4-
This is a simple RESTful API built with Node.js and Express, designed to interact with a PostgreSQL database. The API provides endpoints for managing user data and includes authentication features.
5-
6-
## Features
7-
- **Get All Users**: Retrieve a list of all users.
8-
- **Get User by ID**: Retrieve a specific user by their ID.
9-
- **Create User**: Add a new user to the database.
10-
- **Update User**: Update details of an existing user.
11-
- **Delete User**: Remove a user from the database.
12-
- **User Authentication**: Secure API access using JSON Web Tokens (JWT).
13-
14-
## Technologies Used
15-
- Node.js
16-
- Express
17-
- PostgreSQL
18-
- Body-parser
19-
- JSON Web Token (JWT)
20-
21-
## Installation
22-
1. **Clone the repository**:
23-
```bash
24-
git clone https://github.com/JawherKl/node-api-postgres.git
25-
cd node-api-postgres
26-
```
27-
28-
2. **Install dependencies**:
29-
```bash
30-
npm install
31-
```
32-
33-
3. **Set up PostgreSQL**:
34-
Ensure you have PostgreSQL installed and running. Create a database and a `users` table as per your requirements.
35-
36-
4. **Configure Database Connection**:
37-
Update the `db.js` file to set up your PostgreSQL connection details.
38-
39-
5. **Generate a Random JWT Secret Key** (Optional):
40-
If you want to generate a random JWT secret key, you can use:
41-
```bash
42-
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
43-
```
44-
## Inject Table
45-
``` sql
46-
CREATE TABLE users (
47-
id SERIAL PRIMARY KEY,
48-
name VARCHAR(100) NOT NULL,
49-
email VARCHAR(255) UNIQUE NOT NULL,
50-
password VARCHAR(255) NOT NULL,
51-
role VARCHAR(20) DEFAULT 'user', -- Role-based access control
52-
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
53-
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
54-
deleted_at TIMESTAMP NULL -- For soft delete functionality
55-
);
56-
```
57-
### Explanation of Columns:
58-
1. `id`: A unique identifier for each user (auto-incrementing).
59-
60-
2. `name`: The user's name, with a maximum length of 100 characters.
61-
62-
3. `email`: A unique email address for each user, with a maximum length of 255 characters.
63-
64-
4. `password`: A hashed password stored securely.
65-
66-
5. `role`: The role of the user, e.g., user, admin. Default is user
67-
68-
6. `created_at`: A timestamp of when the record was created.
692

70-
7. `updated_at`: A timestamp of the last update (auto-updates on record modification).
71-
72-
8. `deleted_at`: A nullable field to mark the user as deleted without removing the record.
3+
![nodepost](https://github.com/user-attachments/assets/6f206c6e-dea0-4045-8baa-a04e74a5fbf8)
734

74-
## Usage
75-
Start the server:
76-
```bash
77-
node index.js
78-
```
5+
This is a modern RESTful API built with **Node.js** and **Express**, designed to interact with a **PostgreSQL** database. The API provides various endpoints for managing user data, with additional features like authentication, JWT protection, soft deletion, and automated testing. We've also integrated **Swagger** for auto-generated API documentation.
6+
7+
## Features 🚀
8+
- **User Management**:
9+
- **Get All Users**: Retrieve a list of all users.
10+
- **Get User by ID**: Retrieve a specific user by their ID.
11+
- **Create User**: Add a new user to the database.
12+
- **Update User**: Update details of an existing user.
13+
- **Delete User**: Remove a user from the database (soft delete functionality).
14+
15+
- **Authentication & Authorization**:
16+
- **User Authentication**: Secure API access using **JSON Web Tokens (JWT)**.
17+
- **Role-based Access Control (RBAC)**: Control access to resources based on user roles (e.g., admin, user).
18+
19+
- **Swagger API Documentation**:
20+
- **Swagger** integrated for real-time API documentation and testing directly in the browser. Access the documentation at: [http://localhost:3000/api-docs](http://localhost:3000/api-docs).
21+
22+
- **Database**:
23+
- Integration with **PostgreSQL** for storing user data securely.
24+
- **Soft delete functionality**: Mark users as deleted without removing their data.
25+
26+
- **Unit Testing**:
27+
- Comprehensive unit tests using **Mocha** and **Chai** to ensure the reliability of the application.
28+
- **Test Cases**: Includes tests for user creation, update, deletion, and authentication.
29+
30+
## Technologies Used ⚙️
31+
- **Node.js** (JavaScript runtime)
32+
- **Express** (Web framework)
33+
- **PostgreSQL** (Database)
34+
- **JSON Web Token (JWT)** (Authentication)
35+
- **Body-Parser** (Parsing JSON request bodies)
36+
- **Swagger** (API documentation)
37+
- **Mocha** (Testing framework)
38+
- **Chai** (Assertion library)
39+
40+
## Installation 🛠️
41+
42+
### Step 1: Clone the Repository
43+
```bash
44+
git clone https://github.com/JawherKl/node-api-postgres.git
45+
cd node-api-postgres
46+
```
47+
48+
### Step 2: Install Dependencies
49+
```bash
50+
npm install
51+
```
52+
53+
### Step 3: Set up PostgreSQL
54+
Ensure you have **PostgreSQL** installed and running. Create a new database and configure the connection.
55+
56+
### Step 4: Configure Database Connection
57+
Update the `db.js` file to set up your PostgreSQL connection credentials.
58+
59+
### Step 5: Generate JWT Secret (Optional)
60+
Generate a random JWT secret key (recommended for production environments):
61+
```bash
62+
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
63+
```
64+
65+
### Inject Table into PostgreSQL
66+
```sql
67+
CREATE TABLE users (
68+
id SERIAL PRIMARY KEY,
69+
name VARCHAR(100) NOT NULL,
70+
email VARCHAR(255) UNIQUE NOT NULL,
71+
password VARCHAR(255) NOT NULL,
72+
role VARCHAR(20) DEFAULT 'user', -- Role-based access control
73+
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
74+
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
75+
deleted_at TIMESTAMP NULL -- For soft delete functionality
76+
);
77+
```
78+
79+
### Column Explanation
80+
- `id`: Unique identifier for each user (auto-increment).
81+
- `name`: User's name (max 100 characters).
82+
- `email`: Unique email address (max 255 characters).
83+
- `password`: Hashed password for security.
84+
- `role`: User's role (e.g., admin, user).
85+
- `created_at`: Timestamp for record creation.
86+
- `updated_at`: Timestamp for last update (auto-updates on modification).
87+
- `deleted_at`: Nullable timestamp for soft deletion.
88+
89+
## Usage 🏃‍♂️
90+
91+
### Start the Server
92+
```bash
93+
node index.js
94+
```
7995
The server will run on [http://localhost:3000].
8096

81-
## API Endpoints:
97+
### Access Swagger API Docs
98+
Once the server is running, you can access the auto-generated API documentation powered by Swagger at:
99+
[http://localhost:3000/api-docs](http://localhost:3000/api-docs).
100+
101+
## API Endpoints 📡
82102
- **GET /** - Returns a simple welcome message.
83-
- **GET /users** - Returns all users.
84-
- **GET /users/:id** - Returns a user by ID.
85-
- **POST /users** - Creates a new user (requires JSON body).
86-
- **PUT /users/:id** - Updates an existing user by ID (requires JSON body).
87-
- **DELETE /users/:id** - Deletes a user by ID.
88-
- **POST /login** - Authenticates a user and returns a JWT (requires JSON body with email and password).
103+
- **GET /users** - Get all users.
104+
- **GET /users/:id** - Get a user by ID.
105+
- **POST /users** - Create a new user (requires JSON body).
106+
- **PUT /users/:id** - Update an existing user by ID (requires JSON body).
107+
- **DELETE /users/:id** - Delete a user by ID.
108+
- **POST /login** - Authenticate a user and return a JWT (requires JSON body with email and password).
89109

90-
## Example Requests
110+
## Example Requests 📝
91111

92112
### Get All Users
93-
```bash
94-
curl -X GET http://localhost:3000/users
95-
```
113+
```bash
114+
curl -X GET http://localhost:3000/users
115+
```
96116

97117
### Create User
98-
```bash
99-
curl -X POST http://localhost:3000/users -H "Content-Type: application/json" -d '{"name": "John Doe", "email": "[email protected]"}'
100-
```
118+
```bash
119+
curl -X POST http://localhost:3000/users -H "Content-Type: application/json" -d '{"name": "John Doe", "email": "[email protected]", "password": "password"}'
120+
```
101121

102122
### Update User
103-
```bash
104-
curl -X PUT http://localhost:3000/users/1 -H "Content-Type: application/json" -d '{"name": "Jane Doe"}'
105-
```
123+
```bash
124+
curl -X PUT http://localhost:3000/users/1 -H "Content-Type: application/json" -d '{"name": "Jane Doe"}'
125+
```
106126

107127
### Delete User
108-
```bash
109-
curl -X DELETE http://localhost:3000/users/1
110-
```
128+
```bash
129+
curl -X DELETE http://localhost:3000/users/1
130+
```
111131

112132
### Authenticate User
133+
```bash
134+
curl -X POST http://localhost:3000/login -H "Content-Type: application/json" -d '{"email": "[email protected]", "password": "password"}'
135+
```
136+
137+
### Access Protected Route
138+
```bash
139+
curl -X GET http://localhost:3000/users -H "Authorization: Bearer your_jwt_token"
140+
```
141+
142+
## Unit Testing 🧪
143+
Unit tests are implemented using **Mocha** and **Chai**. To run tests:
144+
145+
1. Install **test dependencies** (if not installed):
113146
```bash
114-
curl -X POST http://localhost:3000/login -H "Content-Type: application/json" -d '{"email": "[email protected]", "password": "your_password"}'
147+
npm install --save-dev mocha chai
115148
```
116149

117-
### Access Protected Route
150+
2. Run the tests:
118151
```bash
119-
curl -X GET http://localhost:3000/users -H "Authorization: Bearer your_jwt_token"
152+
npm test
120153
```
121154

122-
## Contributing
123-
Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.
155+
This will run all tests and output the results to the console. You can find the test cases for different routes and operations in the `test` folder.
156+
157+
## Contributing 🤝
158+
Contributions are welcome! If you have suggestions, improvements, or bug fixes, please open an issue or submit a pull request.
124159

125-
## License
126-
This project is licensed under the MIT License. See the LICENSE file for details.
160+
## License 📝
161+
This project is licensed under the **MIT License**. See the [LICENSE](./LICENSE) file for details.
127162

128-
## Acknowledgments
129-
- Thanks to the contributors and the open-source community for their support.
130-
- Special thanks to the maintainers of the libraries used in this project.
163+
## Acknowledgments 🙏
164+
- Special thanks to all contributors and the open-source community.
165+
- Gratitude to the maintainers of the libraries used in this project.

0 commit comments

Comments
 (0)