Skip to main content

​
Overview

This guide will get you from zero to making your first API call in under 5 minutes. We’ll use SQLite for quick setup, but PostgreSQL is recommended for production.
For a complete production setup with PostgreSQL, Redis, and Celery, see the Installation Guide.

​
Prerequisites

Before you begin, ensure you have:
  • Python 3.11+ installed on your system
  • Git for cloning the repository
  • Basic familiarity with command line operations

​
Installation

1

Clone the Repository

Clone the FKApi repository to your local machine:
git clone <repository-url>
cd FKApi/fkapi
2

Create Virtual Environment

Create and activate a Python virtual environment:
python -m venv venv
source venv/bin/activate

python -m venv venv
venv\Scripts\activate
3

Install Dependencies

Install all required Python packages:
pip install -r requirements.txt
This installs Django 5.0.4, Django Ninja, PostgreSQL adapter, BeautifulSoup4, Redis client, and other dependencies.
4

Configure Environment

Create a .env file from the example:
cp .env.example .env
For quickstart, edit .env with minimal settings:
.env
# Django Settings
DJANGO_DEBUG=True
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1
DJANGO_PORT=8000

# PostgreSQL Database
POSTGRES_DB=fkapi
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_HOST=localhost
POSTGRES_PORT=5432

# Scraper Settings
SCRAPER_USER_AGENT=FootballKitArchiveBot/1.0 (contact@youremail.com)
The SCRAPER_USER_AGENT must include your contact information for ethical scraping.
5

Set Up Database

Create the PostgreSQL database and run migrations:
# Create database
createdb fkapi

# Run migrations
python manage.py migrate

# Start PostgreSQL in Docker
docker run -d --name fkapi-postgres \
  -e POSTGRES_DB=fkapi \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:15

# Run migrations
python manage.py migrate
6

Create Superuser

Create an admin user for the Django admin interface:
python manage.py createsuperuser
Follow the prompts to set username, email, and password.
7

Start the Server

Launch the development server:
python manage.py runserver
You should see:
Starting development server at http://127.0.0.1:8000/

​
Your First API Call

​
Health Check

Verify the API is running: 
curl http://localhost:8000/api/health

import requests

response = requests.get('http://localhost:8000/api/health')
print(response.json())

fetch('http://localhost:8000/api/health')
  .then(res => res.json())
  .then(data => console.log(data));
Expected response: 
{
  "status": "ok",
  "database": "connected",
  "cache": "available"
}

​
Populating Data

The database starts empty! You need to populate it with data through web scraping.

​
Test Scraping (Single Kit)

Before bulk scraping, test with a single kit: 
python manage.py scrape_kit_by_slug --slug "arsenal-2024-home-kit"

​
Search for the Kit

Once scraped, search for kits: 
curl "http://localhost:8000/api/kits?page=1&page_size=10"

import requests

response = requests.get(
    'http://localhost:8000/api/kits',
    params={'page': 1, 'page_size': 10}
)
kits = response.json()
print(f"Found {len(kits)} kits")

​
Search Clubs

Search for clubs with fuzzy matching: 
curl "http://localhost:8000/api/clubs/search?keyword=arsenal&page_size=5"
Response: 
[
  {
    "id": 1,
    "name": "Arsenal",
    "slug": "arsenal-kits",
    "logo": "https://...",
    "country": "GB"
  }
]

​
Interactive API Documentation

Explore all endpoints in the auto-generated Swagger UI: 
http://localhost:8000/api/docs
Features:
  • Try out endpoints directly in the browser
  • View request/response schemas
  • See all available parameters and filters
  • Copy code examples in multiple languages

​
Common Endpoints

Here are the most commonly used endpoints:

Search Clubs

GET /api/clubs/search?keyword={term}
Fuzzy search with accent-insensitive matching

Get Club Kits

GET /api/clubs/{club_id}/kits
All kits for a specific club

List Kits

GET /api/kits?page=1&page_size=20
Paginated kit listing

Search Seasons

GET /api/seasons/search?keyword=2024
Priority-based season matching

​
Next Steps

1

Explore More Endpoints

Visit the API Reference to see all available endpoints and their parameters
2

Populate Your Database

Learn ethical scraping practices in the Getting Started guide to populate your database responsibly
3

Production Setup

Follow the Installation Guide for PostgreSQL, Redis caching, and Celery configuration
4

Configure Rate Limiting

Set up IP whitelisting and adjust rate limits for your use case

​
Troubleshooting

​
Database Connection Errors

If you see database connection errors: 
# Verify PostgreSQL is running
pg_isready

# Check database exists
psql -l | grep fkapi

# Test connection
psql -U postgres -d fkapi

​
Empty API Responses

If endpoints return empty arrays []:
This is normal! The database starts empty. You need to scrape data using management commands like scrape_kit_by_slug or scrape_whole_club.

​
Port Already in Use

If port 8000 is occupied: 
# Use a different port
python manage.py runserver 8001

​
Migration Errors

If migrations fail: 
# Reset migrations (development only)
python manage.py migrate --run-syncdb

​
Getting Help

  • Check the Installation Guide for detailed setup instructions
  • Visit the API documentation at http://localhost:8000/api/docs
  • Review the source code on GitHub
  • Check the CHANGELOG.md for version-specific notes