Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/hazemelakbawy/todo-list-api

A RESTful API for managing to-do lists with user authentication. Built with Java 22 and Spring Boot, it features CRUD operations, token-based authentication, and documentation via Swagger UI. Docker support included for easy deployment.
https://github.com/hazemelakbawy/todo-list-api

docker docker-compose java maven mysql rest-api spring-boot spring-data-jpa spring-security swagger-ui todo-list-api

Last synced: 5 days ago
JSON representation

Host: GitHub
URL: https://github.com/hazemelakbawy/todo-list-api
Owner: HazemElakbawy
License: mit
Created: 2024-10-06T15:43:50.000Z (about 1 month ago)
Default Branch: main
Last Pushed: 2024-10-15T17:03:05.000Z (22 days ago)
Last Synced: 2024-11-02T01:07:33.171Z (5 days ago)
Topics: docker, docker-compose, java, maven, mysql, rest-api, spring-boot, spring-data-jpa, spring-security, swagger-ui, todo-list-api
Language: Java
Homepage:
Size: 32.2 KB
Stars: 1
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# To-Do List API 📝

- This project is a RESTful API for managing a to-do list with user authentication.
- It provides endpoints for user registration, login, and CRUD operations on to-do items.
- This project is part of the community-driven projects published
on [roadmap.sh](https://roadmap.sh/projects/todo-list-api).
- Feel free to visit the [projects page](https://roadmap.sh/projects) to explore more.

## Technologies Used 🛠️

- Java 22 ☕
- Spring Boot 🍃
- Spring Security 🔒
- Spring Data JPA 📊
- MySQL 🐬️
- Docker & Docker Compose 🐳
- Maven 📦
- Swagger UI 📚

## Features 🌟

- User registration and authentication
- Create, read, update, and delete to-do items
- Pagination and filtering for to-do list
- Token-based authentication with refresh token mechanism
- Error handling and security measures
- Data validation
- API documentation using Swagger UI

## Prerequisites ⚙️

- Java 22 JDK
- Docker and Docker Compose
- Maven

## Getting Started 🚀

1. Clone the repository:
```
git clone https://github.com/yourusername/todo-list-api.git
cd todo-list-api
```

2. Build the project:
```
mvn clean package
```

3. Start the application and database using Docker Compose:
```
docker-compose up -d
```

4. The API will be available at `http://localhost:8080`

## Swagger UI 📊

- You can explore and test the API using Swagger UI. After starting the application, open the following URL in your
browser: `http://localhost:8080/swagger-ui/index.html`
- This will load the interactive Swagger interface where you can view API documentation, test API endpoints, and inspect
request/response details.

## API Endpoints 🔗

### User Registration

- `POST /register`
- Request:
```json
{
"username": "John Doe",
"email": "[email protected]",
"password": "password"
}
```
- Response:
```json
{
"refreshToken": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJqb2huQGRvZS5jb20iLCJpYXQiOjE3MjkwMTExMjYsImV4cCI6MTcyOTYxNTkyNn0.UKJ0N32v2cmREU46FbOoe0kF-LqizTi6TY5IO0y8xNyEvUt6ql9QfkhP1nO92uMb67ZQjqKOYI5KyF00GdgQzw",
"accessToken": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJqb2huQGRvZS5jb20iLCJpYXQiOjE3MjkwMTExMjYsImV4cCI6MTcyOTAxODMyNn0.iKEb1nItMmSzCw868CdFCipY82W0_MyWDRL19EYYcj7-K7GGUauo6WjpdEIQ84sOWEwyhj7GY7tRqpLKkGsosQ"
}
```

### User Login

- `POST /login`
- Request:
```json
{
"email": "[email protected]",
"password": "password"
}
```
- Response:
```json
{
"refreshToken": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJqb2huQGRvZS5jb20iLCJpYXQiOjE3MjkwMTExMjYsImV4cCI6MTcyOTYxNTkyNn0.UKJ0N32v2cmREU46FbOoe0kF-LqizTi6TY5IO0y8xNyEvUt6ql9QfkhP1nO92uMb67ZQjqKOYI5KyF00GdgQzw",
"accessToken": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJqb2huQGRvZS5jb20iLCJpYXQiOjE3MjkwMTExMjYsImV4cCI6MTcyOTAxODMyNn0.iKEb1nItMmSzCw868CdFCipY82W0_MyWDRL19EYYcj7-K7GGUauo6WjpdEIQ84sOWEwyhj7GY7tRqpLKkGsosQ"
}
```

### Refresh Token

- `POST /refresh-token`
- Headers: `Authorization: Bearer `
- Response:
```json
{
"refreshToken": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJqb2huQGRvZS5jb20iLCJpYXQiOjE3MjkwMTExMjYsImV4cCI6MTcyOTYxNTkyNn0.UKJ0N32v2cmREU46FbOoe0kF-LqizTi6TY5IO0y8xNyEvUt6ql9QfkhP1nO92uMb67ZQjqKOYI5KyF00GdgQzw",
"accessToken": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJqb2huQGRvZS5jb20iLCJpYXQiOjE3MjkwMTExMjYsImV4cCI6MTcyOTAxODMyNn0.iKEb1nItMmSzCw868CdFCipY82W0_MyWDRL19EYYcj7-K7GGUauo6WjpdEIQ84sOWEwyhj7GY7tRqpLKkGsosQ"
}
```

### Create a To-Do Item

- `POST /todos`
- Headers: `Authorization: Bearer `
- Request:
```json
{
"title": "Buy groceries",
"description": "Buy milk, eggs, and bread"
}
```
- Response:
```json
{
"id": 1,
"title": "Buy groceries",
"description": "Buy milk, eggs, and bread"
}
```

### Update a To-Do Item

- `PUT /todos/{id}`
- Headers: `Authorization: Bearer `
- Request:
```json
{
"title": "Buy groceries",
"description": "Buy milk, eggs, bread, and cheese"
}
```
- Response:
```json
{
"id": 1,
"title": "Buy groceries",
"description": "Buy milk, eggs, bread, and cheese"
}
```

### Delete a To-Do Item

- `DELETE /todos/{id}`
- Headers: `Authorization: Bearer `
- Response: 204 No Content

### Get To-Do Items

- `GET /todos?page=1&limit=10`
- Headers: `Authorization: Bearer `
- Response:
```json
{
"data": [
{
"id": 1,
"title": "Buy groceries",
"description": "Buy milk, eggs, bread"
},
{
"id": 2,
"title": "Pay bills",
"description": "Pay electricity and water bills"
}
],
"page": 1,
"limit": 10,
"total": 2
}
```

## Security 🔒

- Passwords are hashed before storing in the database
- Token-based authentication is implemented, including refresh tokens.
- Input validation is performed on all endpoints

## Error Handling ⚠️

The API uses appropriate HTTP status codes and error messages:

- 400 Bad Request: For invalid input
- 401 Unauthorized: For authentication failures
- 403 Forbidden: For authorization failures
- 404 Not Found: For resources that don't exist
- 500 Internal Server Error: For server-side errors