https://github.com/panastasiadis/starwars-api
A FastAPI-powered asynchronous REST API for exploring Star Wars data. It syncs from SWAPI, stores data in PostgreSQL with SQLModel, manages migrations via Alembic, and runs seamlessly in Docker. Features include typed Pydantic responses, pagination, and full test coverage with pytest.
https://github.com/panastasiadis/starwars-api
alembic api asyncio backend docker fastapi postgresql python restapi sqlmodel starwars swapi
Last synced: 29 days ago
JSON representation
A FastAPI-powered asynchronous REST API for exploring Star Wars data. It syncs from SWAPI, stores data in PostgreSQL with SQLModel, manages migrations via Alembic, and runs seamlessly in Docker. Features include typed Pydantic responses, pagination, and full test coverage with pytest.
- Host: GitHub
- URL: https://github.com/panastasiadis/starwars-api
- Owner: panastasiadis
- Created: 2025-09-12T07:33:10.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-09-15T18:43:42.000Z (9 months ago)
- Last Synced: 2025-09-15T20:30:30.204Z (9 months ago)
- Topics: alembic, api, asyncio, backend, docker, fastapi, postgresql, python, restapi, sqlmodel, starwars, swapi
- Language: Python
- Homepage:
- Size: 68.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# StarWars API
A FastAPI-based asynchronous REST API for Star Wars data, featuring films, characters, and starships. Data is synchronized from the public API **https://swapi.info** and stored in a PostgreSQL database. The project uses SQLModel ORM, Alembic for migrations, and is containerized with Docker.
## Features
- **Async FastAPI** backend
- **PostgreSQL** database (via Docker)
- **SQLModel** ORM
- **Alembic** migrations
- **SWAPI sync** endpoint
- **Paginated endpoints** for films, characters, starships
- **Typed responses** with Pydantic schemas
- **Unit tests** with pytest and httpx
## Setup
### 1. Clone the repository
```sh
git clone https://github.com/yourusername/starwars-api.git
cd starwars-api
```
### 2. Configure environment variables
Copy `.env.example` to `.env` and fill in your database credentials:
```sh
cp .env.example .env
# Edit .env with your settings (see example below)
```
Example `.env`:
```
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=starwars_db
```
### 3. Build and start with Docker Compose
```sh
docker compose up --build
```
This will start both the PostgreSQL database and the FastAPI app.
### 4. Apply database migrations
Open a shell in the API container:
```sh
docker compose exec srv-starwars-api bash
```
Run Alembic migrations:
```sh
uv run alembic upgrade head
```
### 5. Sync Star Wars data
Use the `/api/sync` endpoint to fetch and store SWAPI data:
```sh
curl -X POST http://localhost:8000/api/sync
```
## Usage
- API docs: [http://localhost:8000/docs](http://localhost:8000/docs)
- Example endpoints:
- `GET /api/films`
- `GET /api/characters`
- `GET /api/starships`
- `POST /api/sync`
## Running Tests
Tests are located in `starwars-api-app/app/tests/`.
To run all tests:
```sh
docker compose exec srv-starwars-api bash
uv run pytest --cov=app
```
## Test Coverage Report
