User Endpoints

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:

string

required

Unique username for the user

string

Full name of the user

string

API URL for the user detail endpoint

string

User’s email address (unique)

string

User’s biography text

string

User’s location

string

URL to user’s avatar image

boolean

Whether the user’s profile is private

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/"
  }
]

{
  "detail": "Authentication credentials were not provided."
}

Example Request

curl -X GET "http://localhost:8000/api/users/" \
  -H "Authorization: Token your_auth_token_here"

import requests

url = "http://localhost:8000/api/users/"
headers = {
    "Authorization": "Token your_auth_token_here"
}

response = requests.get(url, headers=headers)
print(response.json())

fetch('http://localhost:8000/api/users/', {
  method: 'GET',
  headers: {
    'Authorization': 'Token your_auth_token_here'
  }
})
.then(response => response.json())
.then(data => console.log(data));

Retrieve User

GET /api/users/{username}/

Retrieve details for a specific user by username. Authentication Required: Yes Path Parameters

string

required

The username of the user to retrieve

Response

{
  "username": "johndoe",
  "name": "John Doe",
  "url": "http://localhost:8000/api/users/johndoe/"
}

{
  "detail": "Not found."
}

Example Request

curl -X GET "http://localhost:8000/api/users/johndoe/" \
  -H "Authorization: Token your_auth_token_here"

import requests

url = "http://localhost:8000/api/users/johndoe/"
headers = {
    "Authorization": "Token your_auth_token_here"
}

response = requests.get(url, headers=headers)
print(response.json())

fetch('http://localhost:8000/api/users/johndoe/', {
  method: 'GET',
  headers: {
    'Authorization': 'Token your_auth_token_here'
  }
})
.then(response => response.json())
.then(data => console.log(data));

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/"
}

{
  "detail": "Authentication credentials were not provided."
}

Example Request

curl -X GET "http://localhost:8000/api/users/me/" \
  -H "Authorization: Token your_auth_token_here"

import requests

url = "http://localhost:8000/api/users/me/"
headers = {
    "Authorization": "Token your_auth_token_here"
}

response = requests.get(url, headers=headers)
print(response.json())

fetch('http://localhost:8000/api/users/me/', {
  method: 'GET',
  headers: {
    'Authorization': 'Token your_auth_token_here'
  }
})
.then(response => response.json())
.then(data => console.log(data));

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

string

required

The username of the user to update

Request Body

string

Username (must be unique)

string

Full name of the user

Response

{
  "username": "johndoe",
  "name": "John Doe Updated",
  "url": "http://localhost:8000/api/users/johndoe/"
}

{
  "username": [
    "A user with that username already exists."
  ]
}

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"
  }'

import requests

url = "http://localhost:8000/api/users/johndoe/"
headers = {
    "Authorization": "Token your_auth_token_here",
    "Content-Type": "application/json"
}
data = {
    "name": "John Doe Updated"
}

response = requests.patch(url, headers=headers, json=data)
print(response.json())

fetch('http://localhost:8000/api/users/johndoe/', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Token your_auth_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'John Doe Updated'
  })
})
.then(response => response.json())
.then(data => console.log(data));

Authentication

Obtain Auth Token

POST /api/auth-token/

Obtain an authentication token for API access. Authentication Required: No Request Body

string

required

User’s username

string

required

User’s password

Response

{
  "token": "9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"
}

{
  "non_field_errors": [
    "Unable to log in with provided credentials."
  ]
}

Example Request

curl -X POST "http://localhost:8000/api/auth-token/" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "password": "your_password"
  }'

import requests

url = "http://localhost:8000/api/auth-token/"
data = {
    "username": "johndoe",
    "password": "your_password"
}

response = requests.post(url, json=data)
token = response.json()["token"]
print(f"Token: {token}")

fetch('http://localhost:8000/api/auth-token/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    username: 'johndoe',
    password: 'your_password'
  })
})
.then(response => response.json())
.then(data => console.log('Token:', data.token));

Error Codes

Bad Request

The request was malformed or contains invalid data

Unauthorized

Authentication credentials were not provided or are invalid

Forbidden

You don’t have permission to access this resource

Not Found

The requested resource was not found

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.

API Overview

Endpoints

FKAPI Integration

Overview

User Model

Endpoints

List Users

Retrieve User

Get Current User (Me)

Update User

Authentication

Obtain Auth Token

Error Codes

Notes

​Overview

​User Model

​Endpoints

​List Users

​Retrieve User

​Get Current User (Me)

​Update User

​Authentication

​Obtain Auth Token

​Error Codes

​Notes

Overview

User Model

Endpoints

List Users

Retrieve User

Get Current User (Me)

Update User

Authentication

Obtain Auth Token

Error Codes

Notes