Updated README
This commit is contained in:
parent
d3c97555e4
commit
b29cb8133a
161
README.md
161
README.md
|
|
@ -1,81 +1,124 @@
|
|||
# Boxes API
|
||||
|
||||
## Overview
|
||||
# Box and Item Management API
|
||||
|
||||
This is a back-end application written in Go that provides an API for managing boxes and items stored within those boxes. It uses SQLite3 as its database and supports JWT-based authentication.
|
||||
This project is a backend API built using Go, designed for managing boxes and the items stored in those boxes. The application is containerized using Docker and uses SQLite3 for data storage. It also supports JWT-based authentication and logs various activities such as logins and box/item operations.
|
||||
|
||||
## Features
|
||||
- Manage boxes and items stored within them.
|
||||
- JWT-based authentication.
|
||||
- Automatic database creation if it doesn't exist.
|
||||
- Configurable using a `config.yaml` file.
|
||||
- Logs logins, box/item creation, and deletion.
|
||||
- Image upload and storage support for items.
|
||||
- Containerized using Docker.
|
||||
|
||||
- **Box Management:** Create, retrieve, and delete boxes.
|
||||
- **Item Management:** Add, retrieve, update, and delete items within boxes.
|
||||
- **Image Storage:** Store images associated with items.
|
||||
- **JWT Authentication:** Secure API access with JSON Web Tokens.
|
||||
- **Configuration:** Manage settings via a `config.yaml` file.
|
||||
- **Logging:** Logs user logins and box/item actions to a file.
|
||||
## Tech Stack
|
||||
- **Language:** Go
|
||||
- **Database:** SQLite3
|
||||
- **Authentication:** JWT
|
||||
- **Containerization:** Docker
|
||||
|
||||
## API Documentation
|
||||
## API Endpoints
|
||||
|
||||
See the [API Specification](api_specification.md) for detailed information on endpoints, request/response formats, and authentication.
|
||||
### Authentication
|
||||
- **POST** `/login`
|
||||
Authenticates a user and returns a JWT.
|
||||
|
||||
## Getting Started
|
||||
### Boxes
|
||||
- **GET** `/boxes`
|
||||
Retrieves all boxes.
|
||||
- **POST** `/boxes`
|
||||
Creates a new box.
|
||||
- **DELETE** `/boxes/{id}`
|
||||
Deletes a box by its ID.
|
||||
- **GET** `/boxes/{id}/items`
|
||||
Retrieves all items in a box by its ID.
|
||||
|
||||
1. **Clone the repository:**
|
||||
### Items
|
||||
- **GET** `/items`
|
||||
Retrieves all items, optionally searchable by description.
|
||||
- **POST** `/items`
|
||||
Adds a new item to a box.
|
||||
- **GET** `/items/{id}`
|
||||
Retrieves an item by its ID.
|
||||
- **PUT** `/items/{id}`
|
||||
Updates an existing item.
|
||||
- **DELETE** `/items/{id}`
|
||||
Deletes an item by its ID.
|
||||
- **GET** `/items/{id}/image`
|
||||
Retrieves the image of an item.
|
||||
- **POST** `/items/{id}/upload`
|
||||
Uploads an image for an item.
|
||||
|
||||
## Configuration
|
||||
|
||||
The application uses a `config.yaml` file to manage configuration settings, such as:
|
||||
|
||||
```yaml
|
||||
database_path: "./data/database.db"
|
||||
jwt_secret: "your_jwt_secret"
|
||||
log_file: "./logs/app.log"
|
||||
image_storage_directory: "./images"
|
||||
```
|
||||
|
||||
## Setup and Running
|
||||
|
||||
### Prerequisites
|
||||
- Docker
|
||||
- Go (if running locally)
|
||||
- SQLite3
|
||||
|
||||
### Running with Docker
|
||||
|
||||
1. Build the Docker image:
|
||||
```bash
|
||||
|
||||
git clone https://github.com/your-username/boxes-api.git
|
||||
|
||||
docker build -t box-management-api .
|
||||
```
|
||||
|
||||
2. Configuration:
|
||||
|
||||
- Create a config.yaml file in the project root directory.
|
||||
- Refer to the config.yaml.example file for available settings.
|
||||
|
||||
3. Database Setup:
|
||||
|
||||
- The database will be automatically created if it doesn't exist.
|
||||
- Configure the database path in the config.yaml file.
|
||||
|
||||
4. Running the Application:
|
||||
|
||||
- Build and run the Go application:
|
||||
|
||||
2. Run the Docker container:
|
||||
```bash
|
||||
|
||||
go run boxes-api .
|
||||
|
||||
docker run -p 8080:8080 box-management-api
|
||||
```
|
||||
|
||||
5. Run the test script:
|
||||
|
||||
``` bash
|
||||
|
||||
./tests.bash
|
||||
|
||||
```
|
||||
|
||||
## Podman Support
|
||||
|
||||
Build the podman image:
|
||||
### Running Locally
|
||||
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
|
||||
podman build -t boxes-api .
|
||||
|
||||
git clone https://github.com/your-repo/box-management-api.git
|
||||
cd box-management-api
|
||||
```
|
||||
|
||||
Run the podman container:
|
||||
|
||||
2. Build the Go application:
|
||||
```bash
|
||||
|
||||
podman run \
|
||||
-e CONFIG="/app/config/config.yaml" \
|
||||
-v /Users/stwhite/CODE/boxes/data:/app/data \
|
||||
-v /Users/stwhite/CODE/boxes/images:/app/images \
|
||||
-v /Users/stwhite/CODE/boxes/config:/app/config \
|
||||
-p 8080:8080 \
|
||||
--name boxes-api-container \
|
||||
localhost/boxes-api
|
||||
|
||||
go build -o main .
|
||||
```
|
||||
|
||||
3. Run the application:
|
||||
```bash
|
||||
./main
|
||||
```
|
||||
|
||||
## Database Schema
|
||||
|
||||
The application creates the following SQLite3 tables:
|
||||
|
||||
- `boxes`: Contains `id` (int) and `name` (text).
|
||||
- `items`: Contains `id` (int), `name` (text), `description` (text), `box_id` (int), and `image_path` (text).
|
||||
- `users`: Contains `id` (int), `username` (text), and `password` (hashed).
|
||||
|
||||
## Authentication
|
||||
|
||||
The API uses JWT-based authentication. A default user is created on startup:
|
||||
|
||||
- **Username**: `boxuser`
|
||||
- **Password**: `boxuser`
|
||||
|
||||
## Logs
|
||||
|
||||
The following events are logged to the file specified in the configuration:
|
||||
- User logins
|
||||
- Box creation/deletion
|
||||
- Item creation/deletion
|
||||
|
||||
## License
|
||||
This project is licensed under the MIT License.
|
||||
|
|
|
|||
Loading…
Reference in New Issue