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:
EndpointPurposeDescription
/api/Internal Server APIsDjango REST Framework endpoints for user management and internal operations
/fkapi/External API ProxyProxy endpoints for Football Kit Archive integration via FKAPI
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: 
{
  "username": "demo_user",
  "name": "Demo User",
  "url": "https://example.com/api/users/demo_user/"
}

​
HTTP Status Codes

The API uses standard HTTP status codes:
CodeDescription
200Successful request
201Resource created successfully
400Bad request - invalid parameters
401Unauthorized - authentication required
403Forbidden - insufficient permissions
404Resource not found
429Too many requests - rate limit exceeded
500Internal server error
503Service unavailable

​
API Documentation

Interactive API documentation is available during development: 
# Available in development mode only
https://your-domain.com/api/docs/
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

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