Why HakiAPI?

Every API client grows the same infrastructure, in the same order. You start with a simple HTTP call. Then you add authentication. Then retries. Then pagination. Then timeout and exception handling. A month later, you've rebuilt the same plumbing you already wrote for the last five projects.

HakiAPI extracts all of that into one reusable core, so every client you build on top of it inherits enterprise-grade behavior automatically. Instead of writing infrastructure, you write business logic.

Without HakiAPI vs. with HakiAPI

✨ Features

Installation

pip install hakiapi

Requires Python 3.10+.

Quick Start

1. The Full-Cycle OAuth 2.0 Engine (Google Calendar)

Stop forcing users to copy and paste authorization codes. HakiAPI handles the complete browser flow, securely saves the state to an atomic file vault, and automatically refreshes expired tokens in the background.

import os
from hakiapi.clients.google_calendar import GoogleCalendarClient
from hakiapi.core.oauth import GoogleOAuthFlow, FileTokenStore

# 1. Set up the secure vault and flow logic
oauth_flow = GoogleOAuthFlow(
    client_id=os.environ.get("GOOGLE_CLIENT_ID"),
    client_secret=os.environ.get("GOOGLE_CLIENT_SECRET"),
    scopes=["https://www.googleapis.com/auth/calendar.readonly"],
    store=FileTokenStore("my_secure_token.json"),
    redirect_port=8765, 
)

# 2. .get_token() does the heavy lifting: 
# It loads the token if valid, silently refreshes if expired, 
# or opens the browser and spins up a local interceptor if missing!
token = oauth_flow.get_token()

# 3. Initialize your client
with GoogleCalendarClient(token=token.access_token) as calendar:
    for event in calendar.events.upcoming(max_results=3):
        print(event.get("summary"))

2. Automatic Pagination (GitHub)

Forget page numbers, while loops, and manually checking for a next page. HakiAPI follows Link headers and cursor pagination automatically, lazily yielding results:

from hakiapi.clients.github import GitHubClient

with GitHubClient() as github:
    # Lazily iterates through every repository, handling all HTTP requests behind the scenes
    for repo in github.get_all_user_repos("torvalds"):
        print(repo["name"])

Exception Handling

Never check HTTP status codes manually again. Every exception inherits from HakiAPIError, carrying the status_code and original response object.

from hakiapi.core.exceptions import AuthenticationError, RateLimitError, ServerError

try:
    github.get_user("torvalds")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except AuthenticationError:
    print("Invalid credentials.")
except ServerError:
    print("GitHub is currently unavailable.")

Architecture & Project Structure

HakiAPI is designed with strict separation of concerns. Every service client inherits production-ready infrastructure automatically.

hakiapi/
├── core/
│   ├── oauth/               # The Self-Healing OAuth 2.0 Engine
│   │   ├── google.py        # Local server interceptor & CSRF protection
│   │   ├── token_store.py   # Atomic file vault for token persistence
│   │   └── refresh.py       # Background token refresh logic
│   ├── auth.py              # Static auth strategies (Bearer, HMAC, API Keys)
│   ├── retry.py             # Exponential-backoff HTTPAdapter factory
│   ├── paginator.py         # Link-header + cursor/token pagination
│   ├── base_client.py       # Request lifecycle & session management
│   └── exceptions.py        # Typed exception hierarchy
│
└── clients/
    ├── github.py            # GitHub API implementation
    ├── gmail.py             # Gmail API implementation
    └── google_calendar.py   # Google Calendar implementation

Create Your Own Client

Creating a new SDK is intentionally simple: subclass BaseAPIClient, point it at a base URL, and define your endpoints as plain methods.

from hakiapi import BaseAPIClient

class WeatherClient(BaseAPIClient):
    def __init__(self, **kwargs):
        super().__init__(base_url="https://api.open-meteo.com/v1", **kwargs)

    def get_weather(self, latitude: float, longitude: float):
        return self.get(
            "forecast",
            params={
                "latitude": latitude,
                "longitude": longitude,
                "current_weather": True,
            },
        )

if __name__ == "__main__":
    # Hyderabad, Telangana, India
    with WeatherClient() as client:
        weather = client.get_weather(latitude=17.385, longitude=78.4867)
        print(weather["current_weather"])

Output

{
    "time": "2026-07-24T22:00",
    "interval": 900, 
    "temperature": 30.6, 
    "windspeed": 13.9, 
    "winddirection": 271, 
    "is_day": 0, 
    "weathercode": 51
}

Authentication, retries, pagination, sessions, and exceptions are entirely inherited — you only write the endpoint logic.

Design Principles

• Infrastructure should be written once.
• API clients should remain lightweight.
• Explicit is better than magical.
• Strong typing improves maintainability.
• Production readiness should be the default, not an afterthought.
• Developer experience matters as much as correctness.

Testing

pip install hakiapi[dev]
pytest

• ✅ 280+ tests passing
• ✅ Core framework covered (auth, retry, paginator, base client, exceptions)
• ✅ Full OAuth 2.0 engine mocked and covered
• ✅ Atomic file vault concurrency tested
• ✅ Client implementations covered

Roadmap

Completed

• Base API framework (BaseAPIClient)
• Authentication system (Bearer, Header, Query, HMAC)
• Retry engine with exponential backoff
• Automatic pagination (Link header + cursor/token)
• Typed exception hierarchy
• Full-cycle OAuth 2.0 Engine (Local server, Vault, Auto-Refresh)
• GitHub, Gmail, & Google Calendar clients

Planned

• Stripe client
• Twitter/X client
• Async client (httpx-based)
• Plugin system

Contributing

Contributions are welcome — bug fixes, documentation, tests, or new clients. Please open an issue before proposing major changes so we can discuss the approach first.

License

MIT License — see LICENSE for details.

⭐ If HakiAPI saved you from rewriting the same API client for the tenth time, consider giving it a star.

It helps more developers discover the project and motivates future development.

Built with ❤️ by Gugilla Aakash