Volcano API

A Python backend project for the My API assignment. The API serves a dataset of 1,250 volcano records and supports public reads, authenticated administration, JWT bearer tokens, pagination, Redis cache, Swagger documentation, and a Postman collection.

Topic

Volcanoes.

The seed script generates more than 1,000 rows in data/volcanoes.json.

Features

• Python FastAPI backend
• Public GET /volcanoes and GET /volcanoes/{id} endpoints
• Pagination with a maximum of 20 records per page
• Admin authentication with OAuth2 password flow and JWT bearer token
• Authenticated create, update, and delete endpoints
• Redis cache support with in-memory fallback
• Swagger documentation at /docs
• Postman collection in postman_collection.json
• Vercel cloud hosting configuration

Local Setup

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python scripts/generate_data.py
uvicorn api.main:app --reload

The API will run at:

http://localhost:8000

Swagger documentation:

http://localhost:8000/docs

Authentication

Default development admin credentials:

username: admin
password: admin123

Get a token:

curl -X POST http://localhost:8000/auth/token ^
  -H "Content-Type: application/x-www-form-urlencoded" ^
  -d "username=admin&password=admin123"

Use the returned access_token as a bearer token for POST, PUT, PATCH, and DELETE.

Endpoints

Method	Path	Auth Required	Description
GET	/health	No	API health check
POST	/auth/token	No	Get JWT bearer token
GET	/volcanoes?page=1&limit=20	No	Paginated volcano list
GET	/volcanoes/{id}	No	Get one volcano
POST	/volcanoes	Yes	Create a volcano
PUT	/volcanoes/{id}	Yes	Replace a volcano
PATCH	/volcanoes/{id}	Yes	Partially update a volcano
DELETE	/volcanoes/{id}	Yes	Delete a volcano

Redis Cache

Set REDIS_URL in .env to use Redis:

REDIS_URL=redis://localhost:6379

If Redis is not configured or unavailable, the API automatically uses an in-memory cache so the project still runs locally.

Postman Documentation

Import postman_collection.json into Postman.

Postman documentation link:

Add your published Postman documentation URL here after publishing the collection.

Cloud URL

Deployment target: Vercel using vercel.json.

Project URL:

https://my-api-subject-1-solution-technical.vercel.app

GitHub repository:

https://github.com/Huseyn777H/my-api

Deploy To Vercel

vercel
vercel --prod

Set these environment variables in Vercel:

JWT_SECRET
ADMIN_USERNAME
ADMIN_PASSWORD
REDIS_URL

REDIS_URL is optional because the app has a memory-cache fallback.

Tests

pytest