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

Đang mở
  • Có gì không ổn?
#201 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
15/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
php
Lĩnh vực
api, backend

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.

Ngôn ngữ chính
PHP
Star
58
Fork
15
Không có pull request nào được merge trong 30 ngày

Chuẩn bị môi trường

  • Có Dockerfile hoặc tệp Docker Compose
  • Không có mẫu pull request
  • Không có hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của StarCitizenWiki/API

Tất cả issue của StarCitizenWiki/API

Issue tương tự

Thêm issue về PHP

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.