Skip to content

README.md

Latest commit

 

History

History
150 lines (102 loc) · 4.69 KB

README.md

File metadata and controls

150 lines (102 loc) · 4.69 KB

Hamkee API

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

asciicast

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.