https://github.com/internethealthreport/ihr-api
Internet Health Report API
https://github.com/internethealthreport/ihr-api
Last synced: about 2 months ago
JSON representation
Internet Health Report API
- Host: GitHub
- URL: https://github.com/internethealthreport/ihr-api
- Owner: InternetHealthReport
- License: gpl-3.0
- Created: 2025-06-02T11:01:00.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-04-24T06:06:36.000Z (about 2 months ago)
- Last Synced: 2026-04-24T07:24:19.067Z (about 2 months ago)
- Language: Python
- Homepage: https://www.ihr.live/ihr/api/
- Size: 234 KB
- Stars: 3
- Watchers: 0
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# IHR API
This project implements the IHR API, migrating from the [old API system](https://github.com/InternetHealthReport/ihr-django) to a more efficient architecture. It introduces a new database management system using [Alembic](https://alembic.sqlalchemy.org/en/latest/) and enhances the structure for creating new endpoints. The API is built on [FastAPI](https://fastapi.tiangolo.com/) and can be run in either a Python virtual environment or using Docker.
---
## Getting Started
### 1. Clone the Repository
```sh
git clone https://github.com/InternetHealthReport/ihr-api.git
```
### 2. Create a `.env` File
In the project root directory, create a new `.env` file to define your specific database connection string, proxy path and page size (number of results to return per page.).
`.env` content:
```env
DATABASE_URL=postgresql://:@:/
PROXY_PATH=ihr/api
PAGE_SIZE=100000
POOL_SIZE=10
MAX_OVERFLOW=5
POOL_TIMEOUT=10
POOL_RECYCLE=1800
REQUEST_TIMEOUT=30
```
---
## Running the Application
You can run this application in one of the following ways:
* Using a Python virtual environment
* Using Docker
---
## Option 1: Run in a Python Virtual Environment
### Step 1: Create and Activate a Virtual Environment
#### On Windows:
```sh
python -m venv venv
venv\Scripts\activate
```
#### On macOS/Linux:
```sh
python3 -m venv venv
source venv/bin/activate
```
### Step 2: Install Dependencies
```sh
pip install -r requirements.txt
```
### Step 3: Run the Application
```sh
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```
---
## Option 2: Run with Docker
### Step 1: Build the Docker Image
```sh
docker build -t ihr-api .
```
### Step 2: Run the Docker Container
#### Using the local Docker Image
```sh
docker run --name ihr-api -p 8000:8000 -d --env-file .env ihr-api
```
#### Using the Docker Hub
```sh
docker run --name ihr-api --env-file .env --restart unless-stopped -p 8000:8000 -d -t internethealthreport/ihr-api:v{v_number}
```
Where `v_number` is the version number.
### (Optional) Step 3: Manage the Container
Start an existing container:
```sh
docker start
```
View logs:
```sh
docker logs -f
```
## Access the API
Once running, you can access:
- API: **[http://localhost:8000](http://localhost:8000)**
- Interactive Docs (Swagger UI): **[http://localhost:8000/docs](http://localhost:8000/docs)**
---
# Documentation
The `docs/` folder contains detailed documentation for various aspects of the project. Below is a list of available documentation files and their descriptions:
### 1. [Project Structure](docs/project_structure.md)
Provides an overview of the project's file and folder structure, organized according to the **Service-Controller-Repository** architectural pattern.
### 2. [Project Architecture](docs/project_architecture.md)
Explains the **Service-Controller-Repository** architecture adopted by the project, highlighting the responsibilities of each layer and how they interact.
### 3. [Database Migration](docs/database_migration.md)
Details how to manage database migrations using Alembic, including TimescaleDB-specific features like hypertables and compression policies.
### 4. [Adding a New Endpoint](docs/add_new_endpoint.md)
A step-by-step guide on how to add a new endpoint to the application.