Quickstart Guide

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

Clone the Repository

Clone the FKApi repository to your local machine:

git clone <repository-url>
cd FKApi/fkapi

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

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.

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.

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

Create Superuser

Create an admin user for the Django admin interface:

python manage.py createsuperuser

Follow the prompts to set username, email, and password.

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

Explore More Endpoints

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

Populate Your Database

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

Production Setup

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

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

Get Started

Core Concepts

Guides

Management Commands

Quickstart Guide

Overview

Prerequisites

Installation

Your First API Call

Health Check

Populating Data

Test Scraping (Single Kit)

Search for the Kit

Search Clubs

Interactive API Documentation

Common Endpoints

Search Clubs

Get Club Kits

List Kits

Search Seasons

Next Steps

Troubleshooting

Database Connection Errors

Empty API Responses

Port Already in Use

Migration Errors

Getting Help

​Overview

​Prerequisites

​Installation

​Your First API Call

​Health Check

​Populating Data

​Test Scraping (Single Kit)

​Search for the Kit

​Search Clubs

​Interactive API Documentation

​Common Endpoints

Search Clubs

Get Club Kits

List Kits

Search Seasons

​Next Steps

​Troubleshooting

​Database Connection Errors

​Empty API Responses

​Port Already in Use

​Migration Errors

​Getting Help

Overview

Prerequisites

Installation

Your First API Call

Health Check

Populating Data

Test Scraping (Single Kit)

Search for the Kit

Search Clubs

Interactive API Documentation

Common Endpoints

Next Steps

Troubleshooting

Database Connection Errors

Empty API Responses

Port Already in Use

Migration Errors

Getting Help