Hamkee API

Hamkee API is a powerful scaffolding tool designed to help developers quickly and easily start implementing an API using FastAPI.

Overview

Starting a new FastAPI project often involves repetitive tasks such as setting up a logger, managing environment variables, and configuring HTTP clients for third-party services. Hamkee API aims to streamline these tasks, allowing you to focus on writing your API endpoints and business logic from the outset.

Features

• Predefined Directory Structure: Provides a well-organized directory structure to manage your code efficiently.
• Batteries Included: Comes with reusable services that offer generic functionalities commonly needed in API development.
• Python Interpreter Management: Automatically handles everything related to the Python interpreter. Specify your desired Python version or let Hamkee API select one for you.
• Docker Integration: Generates Docker and Docker Compose files for containerized deployment, complete with hot-reloading for seamless development.
• Dependency Management: Simplifies managing dependencies and third-party libraries using Rye.

Getting Started

Prerequisites

• Python 3.9+
• Rye (for dependency management)
• Docker and Docker Compose (optional, for containerized deployment)

Installation

1. Clone the repository:

   git clone https://github.com/hamkee-dev-group/hamkee-fastapi.git
   cd hamkee-fastapi

2. Set up the project environment:

   ./scripts/devel/install.sh

   You should see something like:

        ----------------------------------------
        Welcome to Hamkee FastAPI Installation 
        ----------------------------------------
   
   
        ==== Installation Overview ====
   
        ℹ This script will execute the following steps:
   
        1. Create these files:
        - pyproject.toml
        - docker-compose.yml
        - dev.dockerfile
   
        ℹ Do you want to proceed? (y/n)
        y
   
        ==== Creating Project Files ====
   
        ✓ pyproject.toml file created.
        ✓ docker-compose.yml file created.
        ✓ dev.dockerfile file created.
   
        ℹ Do you want to proceed with the installation? (y/n)
        y
   
        ==== Installing Rye ====
   
        ✓ Rye is already installed.
   
        ==== Installing Dependencies ====
   
        → Setting up Python 3.12...

Project Structure

hamkee-fastapi/
├── app/
│   ├── api/                 # API routes
│   ├── core/                # Core functionality and config
│   ├── models/              # Pydantic models
│   ├── services/            # Shared services
│   └── main.py              # Application entry point
├── tests/                   # Test directory
├── docker/                  # Docker configuration
├── pyproject.toml           # Python project configuration
└── README.md                # This file

Usage

Starting the API Locally

PYTHONPATH=`pwd`/app rye run fastapi run app/main.py 

Using Docker

docker compose -f docker-compose.yml up

The API will be available at http://localhost:8000.

API Documentation

Once the server is running, you can access the interactive API documentation:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Configuration

Hamkee API uses environment variables for configuration. Create a .env file in the project root (an env.file.example is provided).

DEBUG=True
...

Development Workflow

1. Create new endpoints in the app/api/ directory
2. Define models, interfaces, protocols and business logic in app/models/
3. Implement services in app/services/
4. Add tests in the tests/ directory
5. Run tests with rye run pytest

Contributing

We welcome contributions from the community! Here's how you can contribute:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -am 'Add new feature'
4. Push to the branch: git push origin feature/my-feature
5. Submit a pull request

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the LICENSE file for details.

The AGPL license ensures that anyone who uses this software over a network must make the source code available to users of that network.

Contact

For questions or support, please open an issue on our GitHub repository.