related_items: expose each variant axis separately instead of one unlabelled axis

Aperta
  • Qualcosa non va?
#201 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
15/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
php
Ambito
api, backend

Direzione di ricerca

This is a design change to the related_items response of GET /api/v2/items?include=related_items, not a small fix. Start by working out which axes the existing one-axis grouping uses, and whether size, grade, manufacturer and type on each item record are enough to build the others. Settle the labelled shape (by_size, by_grade, by_color, set_items) with the maintainers before writing code. Done means each applicable axis is returned separately and labelled, and the sweep numbers in the issue reproduce.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

enhancement

The ask

related_items.variant_items groups items that are identical except along one attribute. Which attribute it is changes from product to product, nothing in the payload says which, and the other axes aren't reachable at all.

Three items, same payload shape, three different meanings:

item size grade variant_items contains axis
Frost-Star SL 0 C Winter-Star SL (size 0, grade D) grade
M4A Cannon 2 A M5A–M9A Cannon (sizes 3-7, all grade A) size
ADP Arms Grey 1 — 23 × ADP Arms * (same size, no grade) colour

These are not exotic relations. M4A Cannon's variants are the size ladder, and Frost-Star SL's are the grade ladder. The API already produces both kinds. What it doesn't do is produce more than one per product, or say which one you got, so a consumer can't tell them apart without refetching every member and diffing the attributes itself.

We'd like related_items to expose each applicable axis separately and label it, rather than returning one unlabelled axis chosen per product:

"related_items": {
  "by_size":   [ ... ],   // same line and grade, other sizes
  "by_grade":  [ ... ],   // same line and size, other grades
  "by_color":  [ ... ],   // identical, other colours
  "set_items": [ ... ]    // same set, other slots (already present)
}

The attributes this needs are already on every item record (size, grade, manufacturer, type), and the API already performs exactly this grouping for one axis. Doing it for the others is the same operation. Doing it once here also avoids every downstream client reimplementing the grouping and drifting from each other.

The grouping itself is sound

Worth saying plainly, because this is a request to extend the model rather than to fix it. Across 12,331 items there are zero base_item chains that fail to self-terminate, zero is_base_variant flags contradicting base_item, and zero base items carrying two different set_names. Of 1,306 groups with more than one member (7,150 items), 99.6% vary along exactly one axis:

group shape count share
size and grade both fixed (colour variants) 1,168 89.4%
grade varies, size fixed 78 6.0%
size varies, grade fixed 55 4.2%
both vary 5 0.4%

The 5 exceptions are all radars, e.g. Denning grouping Abetti (size 1, grade A), Agrippa (size 2, grade A) and Backlund (size 1, grade B). Those look like genuine errors rather than a design choice.

Where a product varies along two axes, only one is reachable

The three items above each vary along a single axis, so returning one is enough. J-Span coolers vary along two, and the naming encodes both:

S0 S1 S2 S3
grade B Cryo-Star SL Cryo-Star Cryo-Star EX Cryo-Star XL
grade C Frost-Star SL Frost-Star Frost-Star EX Frost-Star XL
grade D Winter-Star SL Winter-Star Winter-Star EX Winter-Star XL

related_items returns the column — other grades at the same size, the upgrade path. The row, the same product at other sizes, isn't available at all, despite being visible in the naming and in class_name (COOL_JSPN_S0*_FrostStar*). Nothing indicates a second axis exists.

Three further problems with related_items are independent of this request and cheaper to fix, so they're filed separately:

  • set_name populated from the manufacturer, category or a class identifier — #202
  • items missing grouping data while their own variants are grouped without them — #203
  • cosmetic variant families split across several base_item groups — #204
Reproducing these numbers

Full sweep on 18 September 2026 — the list endpoint accepts the include, so no per-UUID fetching is needed:

GET /api/v2/items?limit=200&page=N&include=related_items&locale=en_EN

62 pages, 12,331 items, no duplicate UUIDs.

count share
set_name present 6,098 49.5%
base_item present 7,150 58.0%
variant_items non-empty 6,773
set_items non-empty 1,755
no grouping data at all 5,053 41.0%

Every item name above links to its record at /api/v2/items/<uuid>?include=related_items&locale=en_EN.

Happy to share the sweep script and resulting items.jsonl, or to re-run it after a change.

Lingua principale
PHP
Stelle
58
Fork
15
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

  • Include un Dockerfile o un file Docker Compose
  • Nessun modello di pull request
  • Nessuna guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di StarCitizenWiki/API

Tutte le issue di StarCitizenWiki/API

Issue simili

Altre issue su PHP

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.