FKAPI – Football Kit Archive API

Documentation Index

Welcome to the Football Kit Archive API documentation. This index will help you find the information you need.

About This Project

The Football Kit Archive API is a Django-based REST API that provides access to a comprehensive database of football (soccer) kit information. The project scrapes and aggregates data from public sources to create a searchable, filterable API for kit enthusiasts, developers, and researchers.

Relation to FootyCollect: This API is an external service used by FootyCollect to create and manage kits, import images, and handle all related data. FootyCollect can run without it, but the API is practically essential for the full experience.

Key Features:

• RESTful API with Django Ninja
• Comprehensive kit database (clubs, seasons, brands, types)
• Advanced search and filtering capabilities
• Ethical web scraping with rate limiting
• Optional Celery integration for background tasks
• Redis caching for improved performance
• Full API documentation with Swagger UI

Disclaimer

⚠️ This is a personal learning project - This project was created for educational purposes and to practice development skills. It is not intended for commercial use or production deployment without proper review and modifications.

Important Notes:

• This project is for learning and skill development purposes
• Code quality, architecture decisions, and implementations reflect a learning journey
• Some features may be experimental or incomplete
• Always review and test thoroughly before using in any production environment
• The project respects robots.txt and implements ethical scraping practices

Table of Contents

1. About This Project
2. Disclaimer
3. Getting Started
4. Core Documentation
5. Development
6. Operations
7. Quick Reference
8. Finding Information
9. Documentation Standards
10. How to Access Documentation

---

Getting Started

Goal	Document
Complete setup from scratch (including initial data population and ethical scraping practices)	Getting Started Guide
Join the project as a new developer	Developer Onboarding

Core Documentation

Setup and Configuration

Topic	Document
End‑to‑end setup (with or without Celery)	Getting Started
Background jobs with Celery (recommended for production)	Celery Setup
System architecture and design decisions	Architecture
Data flow through the system	Data Flow
Production deployment	Deployment Guide

Scraping

Topic	Document
Full guide to ethical scraping	Scraping Guide
Quick reference for common scraping tasks	Quick Scraping

These guides cover:

• Ethical scraping practices (robots.txt, Terms of Service)
• Rate limiting and delays
• Initial data population workflow
• Daily automated scraping
• Troubleshooting

API Documentation

Purpose	Resource
Interactive Swagger/OpenAPI interface (when server is running) ⭐	Interactive API Docs
Browse all available endpoints	API Endpoint Catalog
See code examples for using the API	API Usage Examples
Import endpoints into Postman	Postman Collection

Performance and Optimization

Topic	Document
Caching implementation and configuration	Caching Strategy

Development

Architecture Decisions

Decision	Document
Scraping framework choice	0001: Scraping Framework
Tooling and standards	0002: Tooling and Standards

Operations

Topic	Document
Common issues and solutions	Troubleshooting

Quick Reference

Starting Services

Windows:

# Celery Worker
fkapi\start_celery_worker.bat

# Celery Beat
fkapi\start_celery_beat.bat

Linux/Mac:

# Celery Worker
./fkapi/start_celery_worker.sh

# Celery Beat
./fkapi/start_celery_beat.sh

Common Commands

# Run migrations
python manage.py migrate

# Create superuser
python manage.py createsuperuser

# Scrape latest kits
python manage.py scrape_latest --start-page 1 --end-page 5

# Scrape a club
python manage.py scrape_whole_club --club-slug "arsenal-kits"

# Run tests
pytest

# Lint code
ruff check .
ruff format .

Finding Information

I want to...

I want to…	Go to…
Set up the project from scratch (with or without Celery)	Getting Started Guide
Configure Celery (optional, recommended for production)	Celery Setup
Learn about ethical scraping	Scraping Guide
Get a quick scraping reference	Quick Scraping
Deploy to production	Deployment Guide
Understand the architecture	Architecture
Explore all API endpoints	API Endpoint Catalog
Troubleshoot issues	Troubleshooting
Review architectural decisions	Decision Records
Onboard as a developer	Developer Onboarding

Documentation Standards

All documentation should:

• Be written in English
• Use clear, concise language
• Include code examples where relevant
• Be kept up to date with code changes
• Follow markdown best practices

How to Access Documentation

API Documentation (Interactive) ⭐ PRIMARY

Django Ninja automatically generates an interactive API documentation interface.

1. Start the Django server:

   cd fkapi
   python manage.py runserver

2. Open your browser:

   http://localhost:8000/api/docs
   

Features:

• Interactive Swagger UI
• Test endpoints directly from browser
• View request/response schemas
• See authentication requirements
• Download OpenAPI schema

Project Documentation (Markdown)

Access Methods:

1. Direct File Access: Open .md files in your IDE or text editor
2. GitHub Web Interface: View formatted documentation when pushed to repository
3. Local Server: Use python -m http.server or MkDocs (see Documentation Access Guide)

For detailed information, see: Documentation Access Guide

External Resources

• Django Documentation: https://docs.djangoproject.com/
• Celery Documentation: https://docs.celeryq.dev/
• Redis Documentation: https://redis.io/docs/

---

Last Updated: 2026-03-02 Maintained by: sunr4y