> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fkapi.sunr4y.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart Guide

> Get up and running with FKApi in under 5 minutes

## 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.

<Note>
  For a complete production setup with PostgreSQL, Redis, and Celery, see the [Installation Guide](/installation).
</Note>

## 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

<Steps>
  <Step title="Clone the Repository">
    Clone the FKApi repository to your local machine:

    ```bash theme={null}
    git clone <repository-url>
    cd FKApi/fkapi
    ```
  </Step>

  <Step title="Create Virtual Environment">
    Create and activate a Python virtual environment:

    <CodeGroup>
      ```bash Linux/Mac theme={null}
      python -m venv venv
      source venv/bin/activate
      ```

      ```bash Windows theme={null}
      python -m venv venv
      venv\Scripts\activate
      ```
    </CodeGroup>
  </Step>

  <Step title="Install Dependencies">
    Install all required Python packages:

    ```bash theme={null}
    pip install -r requirements.txt
    ```

    This installs Django 5.0.4, Django Ninja, PostgreSQL adapter, BeautifulSoup4, Redis client, and other dependencies.
  </Step>

  <Step title="Configure Environment">
    Create a `.env` file from the example:

    ```bash theme={null}
    cp .env.example .env
    ```

    For quickstart, edit `.env` with minimal settings:

    ```bash .env theme={null}
    # 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)
    ```

    <Warning>
      The `SCRAPER_USER_AGENT` must include your contact information for ethical scraping.
    </Warning>
  </Step>

  <Step title="Set Up Database">
    Create the PostgreSQL database and run migrations:

    <CodeGroup>
      ```bash PostgreSQL theme={null}
      # Create database
      createdb fkapi

      # Run migrations
      python manage.py migrate
      ```

      ```bash Docker (Alternative) theme={null}
      # 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
      ```
    </CodeGroup>
  </Step>

  <Step title="Create Superuser">
    Create an admin user for the Django admin interface:

    ```bash theme={null}
    python manage.py createsuperuser
    ```

    Follow the prompts to set username, email, and password.
  </Step>

  <Step title="Start the Server">
    Launch the development server:

    ```bash theme={null}
    python manage.py runserver
    ```

    You should see:

    ```
    Starting development server at http://127.0.0.1:8000/
    ```
  </Step>
</Steps>

## Your First API Call

### Health Check

Verify the API is running:

<CodeGroup>
  ```bash cURL theme={null}
  curl http://localhost:8000/api/health
  ```

  ```python Python theme={null}
  import requests

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

  ```javascript JavaScript theme={null}
  fetch('http://localhost:8000/api/health')
    .then(res => res.json())
    .then(data => console.log(data));
  ```
</CodeGroup>

Expected response:

```json theme={null}
{
  "status": "ok",
  "database": "connected",
  "cache": "available"
}
```

## Populating Data

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

### Test Scraping (Single Kit)

Before bulk scraping, test with a single kit:

```bash theme={null}
python manage.py scrape_kit_by_slug --slug "arsenal-2024-home-kit"
```

### Search for the Kit

Once scraped, search for kits:

<CodeGroup>
  ```bash cURL theme={null}
  curl "http://localhost:8000/api/kits?page=1&page_size=10"
  ```

  ```python Python theme={null}
  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")
  ```
</CodeGroup>

### Search Clubs

Search for clubs with fuzzy matching:

```bash theme={null}
curl "http://localhost:8000/api/clubs/search?keyword=arsenal&page_size=5"
```

Response:

```json theme={null}
[
  {
    "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:

<CardGroup cols={2}>
  <Card title="Search Clubs" icon="magnifying-glass">
    ```
    GET /api/clubs/search?keyword={term}
    ```

    Fuzzy search with accent-insensitive matching
  </Card>

  <Card title="Get Club Kits" icon="shirt">
    ```
    GET /api/clubs/{club_id}/kits
    ```

    All kits for a specific club
  </Card>

  <Card title="List Kits" icon="list">
    ```
    GET /api/kits?page=1&page_size=20
    ```

    Paginated kit listing
  </Card>

  <Card title="Search Seasons" icon="calendar">
    ```
    GET /api/seasons/search?keyword=2024
    ```

    Priority-based season matching
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Explore More Endpoints">
    Visit the [API Reference](/api/overview) to see all available endpoints and their parameters
  </Step>

  <Step title="Populate Your Database">
    Learn ethical scraping practices in the Getting Started guide to populate your database responsibly
  </Step>

  <Step title="Production Setup">
    Follow the [Installation Guide](/installation) for PostgreSQL, Redis caching, and Celery configuration
  </Step>

  <Step title="Configure Rate Limiting">
    Set up IP whitelisting and adjust rate limits for your use case
  </Step>
</Steps>

## Troubleshooting

### Database Connection Errors

If you see database connection errors:

```bash theme={null}
# 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 `[]`:

<Note>
  This is normal! The database starts empty. You need to scrape data using management commands like `scrape_kit_by_slug` or `scrape_whole_club`.
</Note>

### Port Already in Use

If port 8000 is occupied:

```bash theme={null}
# Use a different port
python manage.py runserver 8001
```

### Migration Errors

If migrations fail:

```bash theme={null}
# Reset migrations (development only)
python manage.py migrate --run-syncdb
```

## Getting Help

* Check the [Installation Guide](/installation) 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