Skip to content

About

FastAPI starter for Railway with API keys, rate limits and usage metering by UsageRail

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

Repository files navigation

FastAPI metered API starter

A small FastAPI app for Railway where every request needs an API key. The key check, rate limits, quotas and usage counting are done by the UsageRail Python SDK (https://usagerail.com) inside the app, so requests don't pass through a gateway. UsageRail turns the counts into usage billing in your own Stripe account.

What gets deployed

One Railway service running uvicorn with this app:

Route What it does Usage counted
GET /v1/hello Returns {"message": "Hello"} 1 request
POST /v1/word-count Takes {"text": "..."} and returns the number of words 1 request, or one unit per word if your UsageRail app counts units

Every path, including /, goes through the UsageRail middleware first. A request without a valid key gets a 401 before your code runs. A customer over their rate limit, or over a quota set to stop at the limit, gets a 429 with a Retry-After header.

Files:

  • main.py: the app and the middleware setup
  • requirements.txt: usagerail, fastapi, starlette and uvicorn, pinned
  • railway.json: start command uvicorn main:app --host 0.0.0.0 --port $PORT
  • .python-version: Python 3.12

The one variable: USAGERAIL_APP_KEY

The app won't start without it. To get one:

  1. Sign in to the UsageRail console at https://app.usagerail.com and choose New app.
  2. Pick Test mode, the SDK integration, and a key prefix such as acme.
  3. Copy the app key (it starts with urk_test_). The console shows it only once.

Paste it into the service's Variables tab on Railway. The quickstart at https://usagerail.com/docs/quickstart covers these steps and what each field means.

Try it with curl

Give the service a public domain (Settings, Networking, Generate Domain). Then, in the UsageRail console, open Customers, add a customer and create a key for them. Use that key below; acme_test_... stands for it.

curl -i https://your-app.up.railway.app/v1/hello \
  -H "Authorization: Bearer acme_test_..."

The response is 200 with {"message":"Hello"}. Without the header:

curl -i https://your-app.up.railway.app/v1/hello
HTTP/1.1 401 Unauthorized

{"error": "invalid_api_key"}

The key can also go in an X-API-Key header:

curl -i -X POST https://your-app.up.railway.app/v1/word-count \
  -H "X-API-Key: acme_test_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "metered APIs bill per unit"}'

That returns {"words":5}. If the app's Settings say it counts units, this request counts as 5.

To see a rate limit, create a plan under Plans with a limit of 2 requests per second and move the customer to it. The SDK syncs every 15 seconds, so wait for the next sync, then send a burst:

for i in 1 2 3 4 5; do
  curl -s -o /dev/null -w "%{http_code}\n" https://your-app.up.railway.app/v1/hello \
    -H "Authorization: Bearer acme_test_..."
done

Requests over the 2-per-second limit get 429. How many depends on how fast they go out, since the limit refills during the burst.

Counts reach the console's Usage page about a minute after the requests.

Run it locally

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
USAGERAIL_APP_KEY=urk_test_... uvicorn main:app --port 8000

Good to know

  • The SDK sends counts every 60 seconds and once more when uvicorn shuts down on SIGTERM. If the process is killed outright, for example when it runs out of memory, counts it hadn't sent are lost and never billed.
  • If the SDK can't reach UsageRail, it checks synced keys against its local copy for up to 24 hours after the last successful sync. A key it has never seen gets a 503 by default; you can change that in the app's settings.
  • Middleware options, counting units with request.state.usagerail.track(), and using your own login instead of UsageRail keys are covered at https://usagerail.com/docs/fastapi.

License

MIT

About

FastAPI starter for Railway with API keys, rate limits and usage metering by UsageRail

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages