Skip to main content

​
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:
All API endpoints use HTTPS in production. Development environments may use HTTP.

​
Response Format

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

​
HTTP Status Codes

The API uses standard HTTP status codes:

​
API Documentation

Interactive API documentation is available during development:
The Swagger UI at /api/docs/ is only available when DEBUG=True. In production, use the OpenAPI schema at /api/schema/ to generate documentation.

​
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
FKAPI endpoints require the external FKAPI service to be running. See the FKAPI repository for setup instructions.

​
OpenAPI Specification

The API is documented using OpenAPI 3.0 specification, generated by drf-spectacular. The schema includes:
  • Request/response schemas
  • Authentication requirements
  • Endpoint descriptions
  • Example requests and responses
  • Data validation rules

​
Accessing the Schema

Navigate to /api/schema/ to download the OpenAPI schema JSON file.

​
Getting Started

To start using the API:
  1. Obtain an authentication token - See Authentication
  2. Review rate limits - See Rate Limiting
  3. Make your first request - Try the /api/users/me/ endpoint

​
Quick Example

​
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
  • Documentation: Review the architecture docs in the repository