adding docs

Author: MarcelFox

README.md

@@ -0,0 +1,78 @@
+# Reservation API
+
+## Overview
+The **Reservation API** is a RESTful service for managing room reservations. It allows users to create, retrieve, and delete reservations, register rooms, and check availability. Authentication is required for certain endpoints.
+
+## API Information
+- **Title:** Reservation API
+- **Version:** 0.0.1
+- **Description:** Room booking API.
+- **Author:** [Marcel Fox](https://marcelfox.com/)
+- **License:** [MIT](https://mit-license.org/)
+
+## Local Development
+**For information regarding how to run the application locally, visit the [development section](./docs/DEVELOPMENT.md)**
+
+## Authentication
+The API uses **OAuth2 Password Bearer Token** authentication for protected endpoints. Users must obtain a token via the `/token/` endpoint.
+
+## Endpoints
+
+### Health Check
+- **GET /**
+- **Description:** Check API health status.
+- **Response:** `{ "message": "ok" }`
+
+### Authentication
+- **POST /token/**
+- **Description:** Authenticate user and obtain an access token.
+- **Request:** `application/x-www-form-urlencoded` (username & password required)
+- **Response:** Access token
+
+### Reservations
+- **POST /reservations/**
+  - **Description:** Create a new reservation.
+  - **Authentication:** Required
+  - **Request Body:** `{ "user_name": "John Doe", "start_time": "2025-01-22T14:00:00", "end_time": "2025-01-22T16:00:00", "room_id": 1 }`
+  - **Response:** Reservation details
+
+- **GET /reservations/**
+  - **Description:** Retrieve a list of reservations.
+  - **Query Parameters:** `skip` (default: 0), `limit` (default: 10)
+  - **Response:** List of reservations
+
+- **DELETE /reservations/{id}**
+  - **Description:** Remove a reservation by ID.
+  - **Authentication:** Required
+
+### Rooms
+- **GET /rooms/**
+  - **Description:** Retrieve a list of registered rooms.
+  - **Query Parameters:** `skip` (default: 0), `limit` (default: 10)
+  - **Response:** List of rooms
+
+- **POST /rooms/**
+  - **Description:** Register a new room.
+  - **Authentication:** Required
+  - **Request Body:** `{ "name": "Conference Room", "capacity": 10, "location": "Floor 1" }`
+  - **Response:** Room details
+
+- **GET /rooms/{id}/availability**
+  - **Description:** Check room availability for a specific time range.
+  - **Query Parameters:** `start_time`, `end_time`
+  - **Response:** Availability status
+
+- **GET /rooms/{id}/reservation**
+  - **Description:** List reservations for a specific room.
+  - **Query Parameters:** `date` (optional), `skip` (default: 0), `limit` (default: 10)
+  - **Response:** List of reservations for the room
+
+## Error Handling
+The API returns **422 Validation Error** for invalid requests. Errors include:
+- Missing required fields
+- Invalid data formats
+- Unauthorized access
+
+## License
+This project is licensed under the [MIT License](https://mit-license.org/).
+

docs/DEVELOPMENT.md

@@ -0,0 +1,96 @@
+# Development Guide
+
+## Heads-up!
+Before starting development, ensure you:
+- Create a virtual environment and activate it.
+    - A good tool to manage virtualenvs is [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/)
+- Have a PostgreSQL instance running.
+  - For Docker users, it is possible to create a postgres instance running `make run:deb` in an individual terminal.
+- Install dependencies using:
+  ```sh
+  pip install -r requirements.txt
+  ```
+  Alternatively, if you have [Poetry](https://python-poetry.org/) installed globally, you can use:
+  ```sh
+  poetry install
+  ```
+- Execute database migrations using:
+  ```sh
+  alembic upgrade head
+  ```
+
+## Prerequisites
+Ensure you have the following installed:
+- Python (>=3.8)
+- [pip](https://pip.pypa.io/en/stable/)
+- [FastAPI](https://fastapi.tiangolo.com/)
+- [Uvicorn](https://www.uvicorn.org/)
+- [Docker](https://www.docker.com/)
+- [Alembic](https://alembic.sqlalchemy.org/en/latest/)
+- [pytest](https://docs.pytest.org/en/stable/)
+- [Ruff](https://github.com/charliermarsh/ruff)
+- [isort](https://pycqa.github.io/isort/)
+
+## Setup
+1. Install dependencies:
+   ```sh
+   make install
+   ```
+
+## Running the Application
+You can run the application in different environments using the following commands:
+
+### Standard Run
+```sh
+make run
+```
+This starts the application using `fastapi run`.
+
+### Development Mode
+```sh
+make run:dev
+```
+Runs the application in development mode using `fastapi dev`.
+
+### Using Uvicorn
+#### Production Mode
+```sh
+make run:uvi
+```
+Runs the application using `uvicorn` with `0.0.0.0` as the host.
+
+#### Development Mode
+```sh
+make run:uvi:dev
+```
+Runs the application using `uvicorn` with auto-reloading enabled.
+
+### Running with Docker
+```sh
+make run:docker
+```
+Runs the application inside a Docker container using `docker compose`.
+
+## Database Setup
+To start the PostgreSQL database:
+```sh
+make run:db
+```
+
+To apply migrations:
+```sh
+make migrate
+```
+
+## Linting & Formatting
+To format and lint the code:
+```sh
+make lint
+```
+This runs `ruff format` and `isort` on the `src/` directory.
+
+## Running Tests
+To run tests with `pytest`:
+```sh
+make test
+```