Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Project516/BlogAPI/llms.txt

Use this file to discover all available pages before exploring further.

Running your own instance of the Blog API gives you full control over the server, its rate limits, and the data it serves. The setup is straightforward: you need Python 3.12 or later and the uv package manager. The server starts in under a minute and listens on port 8000 by default.

​
Prerequisites

Before you start, make sure you have the following installed:
  • Python 3.12 or later — required by pyproject.toml
  • uv — used to install dependencies and run the server. Install it from docs.astral.sh/uv

​
Steps

1

Clone the repository

Clone the Blog API source code from GitHub:
git clone https://github.com/Project516/BlogAPI
cd BlogAPI
2

Install dependencies

Use uv sync to install all required packages defined in pyproject.toml:
uv sync
The project depends on fastapi, uvicorn, slowapi, beautifulsoup4, and requests. If you prefer not to use uv, you can install directly with pip:
pip install fastapi uvicorn slowapi beautifulsoup4 requests
3

Start the server

You have two options for starting the server.Option 1 — run directly with uv:
uv run main.py
Option 2 — use the provided shell script:
sh run.sh
The run.sh script does three things before launching the server:
run.sh
#!/bin/sh

uv format
uv audit
uv run main.py --reload
  • uv format — formats all Python source files
  • uv audit — checks dependencies for known security vulnerabilities
  • uv run main.py --reload — starts the server with hot-reload enabled, so code changes are picked up automatically
The server listens on 0.0.0.0:8000 once it is running.
4

Populate the cache

The in-memory cache starts empty unless /tmp/cache.json already exists from a previous run. Call POST /blogs/cache to scrape the upstream blog index and fill the cache:
curl -X POST http://localhost:8000/blogs/cache
A successful response looks like:
{
  "message": "Blogs cached successfully"
}
5

Make your first request

Once the cache is populated, fetch all blog posts:
curl http://localhost:8000/blogs
You should receive a JSON array of blog post objects:
[
  {
    "title": "My first post",
    "link": "https://project516.dev/posts/my-first-post",
    "date": "2024-11-01"
  }
]

​
Notes about the cache

The cache is written to /tmp/cache.json after each successful POST /blogs/cache call. On most Linux systems, /tmp is cleared on reboot. After restarting the server following a reboot, call POST /blogs/cache again to repopulate the cache before serving requests.
The server binds to 0.0.0.0:8000 by default, making it reachable on all network interfaces. If you are exposing the API publicly, consider placing it behind a reverse proxy such as nginx or Caddy to handle TLS and restrict access as needed.
For production use, run the server under a process manager so it restarts automatically after a crash or reboot. Two common options are systemd and supervisord. With systemd, create a service unit file that runs uv run main.py and set Restart=always. With supervisord, add a [program:blogapi] block pointing to the same command.

Build docs developers (and LLMs) love

Get started for freeTalk to us