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

# API Introduction

> Overview of the FootyCollect REST API

## Welcome to FootyCollect API

The FootyCollect API provides programmatic access to the FootyCollect platform for managing football memorabilia collections. Built with Django REST Framework, the API follows REST principles and returns JSON-formatted responses.

## Base URLs

FootyCollect exposes two distinct API endpoints:

| Endpoint  | Purpose              | Description                                                                 |
| --------- | -------------------- | --------------------------------------------------------------------------- |
| `/api/`   | Internal Server APIs | Django REST Framework endpoints for user management and internal operations |
| `/fkapi/` | External API Proxy   | Proxy endpoints for Football Kit Archive integration via FKAPI              |

<Note>
  All API endpoints use HTTPS in production. Development environments may use HTTP.
</Note>

## Response Format

All API responses are returned in JSON format with appropriate HTTP status codes:

```json theme={null}
{
  "username": "demo_user",
  "name": "Demo User",
  "url": "https://example.com/api/users/demo_user/"
}
```

### HTTP Status Codes

The API uses standard HTTP status codes:

| Code  | Description                             |
| ----- | --------------------------------------- |
| `200` | Successful request                      |
| `201` | Resource created successfully           |
| `400` | Bad request - invalid parameters        |
| `401` | Unauthorized - authentication required  |
| `403` | Forbidden - insufficient permissions    |
| `404` | Resource not found                      |
| `429` | Too many requests - rate limit exceeded |
| `500` | Internal server error                   |
| `503` | Service unavailable                     |

## API Documentation

Interactive API documentation is available during development:

<CodeGroup>
  ```bash Swagger UI theme={null}
  # Available in development mode only
  https://your-domain.com/api/docs/
  ```

  ```bash OpenAPI Schema theme={null}
  # JSON schema endpoint
  https://your-domain.com/api/schema/
  ```
</CodeGroup>

<Warning>
  The Swagger UI at `/api/docs/` is only available when `DEBUG=True`. In production, use the OpenAPI schema at `/api/schema/` to generate documentation.
</Warning>

## Available Endpoints

### Internal API (`/api/`)

The internal API provides access to:

#### Users

* `GET /api/users/` - List users (filtered to authenticated user)
* `GET /api/users/{username}/` - Retrieve user details
* `PUT /api/users/{username}/` - Update user
* `PATCH /api/users/{username}/` - Partial update user
* `GET /api/users/me/` - Get current authenticated user

### External API Proxy (`/fkapi/`)

The FKAPI proxy endpoints provide access to Football Kit Archive data:

#### Clubs

* `GET /fkapi/clubs/search/?keyword=<query>` - Search clubs
* `GET /fkapi/clubs/{club_id}/seasons/` - Get club seasons
* `GET /fkapi/clubs/{club_id}/seasons/{season_id}/kits/` - Get club kits for season

#### Kits

* `GET /fkapi/kits/search/?keyword=<query>` - Search kits
* `GET /fkapi/kits/{kit_id}/` - Get kit details

#### Other Resources

* `GET /fkapi/brands/search/?keyword=<query>` - Search brands
* `GET /fkapi/competitions/search/?keyword=<query>` - Search competitions
* `GET /fkapi/seasons/search/?keyword=<query>` - Search seasons
* `GET /fkapi/filters/?filter_type=<type>` - Get filter options with counts

<Note>
  FKAPI endpoints require the external FKAPI service to be running. See the [FKAPI repository](https://github.com/sunr4y/fkapi) for setup instructions.
</Note>

## OpenAPI Specification

The API is documented using OpenAPI 3.0 specification, generated by [drf-spectacular](https://drf-spectacular.readthedocs.io/). The schema includes:

* Request/response schemas
* Authentication requirements
* Endpoint descriptions
* Example requests and responses
* Data validation rules

### Accessing the Schema

<Tabs>
  <Tab title="Browser">
    Navigate to `/api/schema/` to download the OpenAPI schema JSON file.
  </Tab>

  <Tab title="curl">
    ```bash theme={null}
    curl -X GET https://your-domain.com/api/schema/ \
      -H "Accept: application/json" \
      -o openapi-schema.json
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.get('https://your-domain.com/api/schema/')
    schema = response.json()
    ```
  </Tab>
</Tabs>

## Getting Started

To start using the API:

1. **Obtain an authentication token** - See [Authentication](/api/authentication)
2. **Review rate limits** - See [Rate Limiting](/api/rate-limiting)
3. **Make your first request** - Try the `/api/users/me/` endpoint

### Quick Example

```bash theme={null}
# 1. Obtain a token
curl -X POST https://your-domain.com/api/auth-token/ \
  -H "Content-Type: application/json" \
  -d '{"username": "your_username", "password": "your_password"}'

# Response: {"token": "9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"}

# 2. Use the token to access protected endpoints
curl -X GET https://your-domain.com/api/users/me/ \
  -H "Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"
```

## API Versioning

The current API version is **v1.0.0**. Future breaking changes will be introduced in new versions with appropriate deprecation notices.

## Support

For API issues or questions:

* GitHub Issues: [FootyCollect Issues](https://github.com/sunr4y/FootyCollect/issues)
* Documentation: Review the architecture docs in the repository