Skip to content

Comments

feat(api): add V2 JSON:API relationship endpoint for PlayerAchievementSet resources#4562

Merged
wescopeland merged 7 commits intoRetroAchievements:masterfrom
wescopeland:v2-api-player-ach-sets
Feb 23, 2026
Merged

feat(api): add V2 JSON:API relationship endpoint for PlayerAchievementSet resources#4562
wescopeland merged 7 commits intoRetroAchievements:masterfrom
wescopeland:v2-api-player-ach-sets

Conversation

@wescopeland
Copy link
Member

This PR adds a V2 API relationship endpoint for PlayerAchievementSet resources. This is a follow-up to #4528.

These resources are accessible by two means:

  1. Directly by GET /users/{user}/player-achievement-sets.
  2. Sideways through GET /users/{user}/player-games?include=playerAchievementSets, which allows per-set breakdowns of the retrieved PlayerGame records.

Things worth noting:

  1. There is no standalone index for PlayerAchievementSet resources. These records only make sense in the context of other related or parent records.
  2. Results are default sorted by -lastUnlockAt (most recent activity first), mirroring PlayerGameSchema's -lastPlayedAt pattern.
  3. The achievementSet and game relationships can be included via ?include=achievementSet or ?include=game.
  4. The filter[gameId] param filters to achievement sets for a specific game (it joins through game_achievement_sets).
  5. A custom UserScopedHasManyThrough relationship class was needed for the sideways player-games?include=playerAchievementSets.
  6. Virtually every field in schema is sortable.

How to test this PR

# Get a paginated list of player achievement sets for a user (50 per page)
curl --request GET \
  --url http://localhost:64000/api/v2/users/Scott/player-achievement-sets \
  --header 'X-API-Key: {redacted}'

# Get player achievement sets with game data included
curl --request GET \
  --url 'http://localhost:64000/api/v2/users/Scott/player-achievement-sets?include=game' \
  --header 'X-API-Key: {redacted}'

# Get player achievement sets with achievement set data included
curl --request GET \
  --url 'http://localhost:64000/api/v2/users/Scott/player-achievement-sets?include=achievementSet' \
  --header 'X-API-Key: {redacted}'

# Filter to a specific game
curl --request GET \
  --url 'http://localhost:64000/api/v2/users/Jamiras/player-achievement-sets?filter[gameId]=11289&include=game' \
  --header 'X-API-Key: {redacted}'

# Include per-set breakdowns on player games
curl --request GET \
  --url 'http://localhost:64000/api/v2/users/Scott/player-games?include=playerAchievementSets' \
  --header 'X-API-Key: {redacted}'

# Apply custom pagination
curl --request GET \
  --url 'http://localhost:64000/api/v2/users/Scott/player-achievement-sets?page[number]=2&page[size]=25' \
  --header 'X-API-Key: {redacted}'

@wescopeland wescopeland requested a review from a team February 14, 2026 15:49
@wescopeland wescopeland enabled auto-merge (squash) February 23, 2026 17:58
@wescopeland wescopeland merged commit 9e9a8ef into RetroAchievements:master Feb 23, 2026
20 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants