Skip to main content

​
Overview

The User API provides endpoints for retrieving and updating user information. All endpoints require authentication via token-based authentication. Base URL: /api/users/ Authentication: Token authentication required. Include the token in the Authorization header: 
Authorization: Token your_auth_token_here

​
User Model

The User model includes the following fields:
​
username
string
required
Unique username for the user
​
name
string
Full name of the user
​
url
string
API URL for the user detail endpoint
​
email
string
User’s email address (unique)
​
biography
string
User’s biography text
​
location
string
User’s location
​
avatar
string
URL to user’s avatar image
​
is_private
boolean
Whether the user’s profile is private
​
created_at
datetime
Timestamp when the user was created

​
Endpoints

​
List Users

GET /api/users/
Retrieve a list of users. Note: This endpoint only returns the authenticated user due to queryset filtering in footycollect/users/api/views.py:17-19. Authentication Required: Yes Response 
[
  {
    "username": "johndoe",
    "name": "John Doe",
    "url": "http://localhost:8000/api/users/johndoe/"
  }
]
Example Request 
curl -X GET "http://localhost:8000/api/users/" \
  -H "Authorization: Token your_auth_token_here"

​
Retrieve User

GET /api/users/{username}/
Retrieve details for a specific user by username. Authentication Required: Yes Path Parameters
​
username
string
required
The username of the user to retrieve
Response 
{
  "username": "johndoe",
  "name": "John Doe",
  "url": "http://localhost:8000/api/users/johndoe/"
}
Example Request 
curl -X GET "http://localhost:8000/api/users/johndoe/" \
  -H "Authorization: Token your_auth_token_here"

​
Get Current User (Me)

GET /api/users/me/
Retrieve the authenticated user’s information. This is a custom action endpoint defined in footycollect/users/api/views.py:21-24. Authentication Required: Yes Response 
{
  "username": "johndoe",
  "name": "John Doe",
  "url": "http://localhost:8000/api/users/johndoe/"
}
Example Request 
curl -X GET "http://localhost:8000/api/users/me/" \
  -H "Authorization: Token your_auth_token_here"

​
Update User

PUT /api/users/{username}/
PATCH /api/users/{username}/
Update user information. Use PUT for full updates or PATCH for partial updates. Authentication Required: Yes Path Parameters
​
username
string
required
The username of the user to update
Request Body
​
username
string
Username (must be unique)
​
name
string
Full name of the user
Response 
{
  "username": "johndoe",
  "name": "John Doe Updated",
  "url": "http://localhost:8000/api/users/johndoe/"
}
Example Request 
curl -X PATCH "http://localhost:8000/api/users/johndoe/" \
  -H "Authorization: Token your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe Updated"
  }'

​
Authentication

​
Obtain Auth Token

POST /api/auth-token/
Obtain an authentication token for API access. Authentication Required: No Request Body
​
username
string
required
User’s username
​
password
string
required
User’s password
Response 
{
  "token": "9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"
}
Example Request 
curl -X POST "http://localhost:8000/api/auth-token/" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "password": "your_password"
  }'

​
Error Codes

​
400
Bad Request
The request was malformed or contains invalid data
​
401
Unauthorized
Authentication credentials were not provided or are invalid
​
403
Forbidden
You don’t have permission to access this resource
​
404
Not Found
The requested resource was not found
​
500
Internal Server Error
An error occurred on the server

​
Notes

The UserViewSet uses username as the lookup field instead of the default ID. All user detail endpoints use the username in the URL path.
The list users endpoint is filtered to only return the authenticated user. This is implemented in footycollect/users/api/views.py:17-19 via the get_queryset method.
For full interactive API documentation with the ability to test endpoints, visit /api/docs/ when running the FootyCollect server.