kingultron99 commented 5 months ago

Gripes

I've recently encountered a few issues/gripes when dealing with armour / weapon items retrieved from the api. I'll expand on these later in this issue, but for brevity, they are as follows:

Variant items cannot be filtered out.
Difficult to programmatically distinguish between a base model or a variant when retrieving all weapons/armour.
Items dont list their variants.
Difficult to link a variant item back to its base model's wiki page

Expanding

beginning with my first gripe:

"Variant items cannot be filtered out".

Frankly there are a LOT of weapons and armour items that are fundamentally the same outside of their respective colorways and being able to filter out these items would reduce clutter and the overwhelming amount of items being presented.

If we want to achieve this at the request/response level, it could be achieved by adding a filter flag that a user can pass into the request url, such as listVariants=[true|false] — or we can let the user distinguish between items themselves, which brings me to:

"Difficult to programmatically distinguish between a base model or a variant"

When requesting weapons / armour from their respective endpoints (/api/v2/weapons and /api/v2/armor respectively) there is no immediate indicator that an item is a variant. This information is only actually given when directly requesting a specific item. For example, A personal weapon will return a base_model attribute containing a direct API link if it is a variant, while a "base model" weapon does not. providing a base_model attribute through the /api/v2/weapons endpoint would allow the user to still retrieve all weapons if they choose, but also the ability to filter out items that contain a base_model attribute when needed

This could be theoratically achieved by adding the base_model attribute to the personal_weapon_link_v2 schema resulting in the following example response:

[
    {
        "uuid": "1aad8334-8d0a-4dd1-bcca-bd195bc013a7",
        "name": "A03 \"Canuto\" Sniper Rifle",
        "type": "Sniper Rifle",
        "class": "Ballistic",
        "manufacturer": {
            "name": "Gemini",
            "code": "GEM",
            "link": "https://api.star-citizen.wiki/api/v2/manufacturers/Gemini"
        },
        "base_model": "https://api.star-citizen.wiki/api/v2/personal-weapons/6b1fb5e8-f9ec-49bc-befb-c81b7c08c5ea",
        "link": "https://api.star-citizen.wiki/api/v2/items/1aad8334-8d0a-4dd1-bcca-bd195bc013a7",
        "updated_at": "2023-12-15T10:02:47.000000Z",
        "version": "3.22.0-LIVE.9003376"
    },
]

This is slightly more annoying when it comes to armour, as some armour variants/colorways dont provide a base_model attribute in their clothing schema at all

"Items dont list their variants"

While I dont think this is particularly important or impactful, I still think it is worth mentioning. I would like for specific item responses to also return a list of its variants, similar to how a vehicle may list its loaners. this would allow for faster traversal over related items, when also providing item variants

"Difficult to link a variant item back to its base model's wiki page"

This issue, I find particularly annoying. being able to provide a link back to an items wiki page, allows me to present a user to see more information about an item by pointing them to that page. with vehicles, I was able to achieve this by formatting the returned ship name and creating a link from it, however item variants do not poses their own dedicated wiki page, and as i'm unable to always reliably or efficiently grab the items base model, I cannot create or provide that link.

Closing off

At the moment, everything outlined above are just gripes, I may have completely missed or overlooked something or could simply be flat-out wrong. If so, please tell me. however, I wish to present this issue as a somewhat open discussion towards how the api may be improved and made more accessible.

octfx commented 5 months ago

Thanks for these detailed improvement requests! I’ll definitely expand the endpoints in question

Armor variants are currently ‘computed’ by checking if an item without a color attribute exists. This is definitely prone to errors, I did not find such an indicator in the game files directly, but will check them again.

octfx commented 4 months ago

I've now changed the endpoints in the following way:

Variants and Base indicator

I've moved the base_model key up to the item response and renamed it to base_variant.
If an item has a base variant, the nullable base_variant key then contains an item_link_v2, also each item now has an is_base_variant boolean key.

Variants of an item can now be included by adding include=variants, an array of item_link_v2 is then available on the variants key.

Note: Variants are only available on the base model, so including variants on a variant yields an empty array.

Variants can further be filtered on "index" endpoints using ?filter[variants]=false

Personal Weapons and Clothing/Armor endpoints

The personal_weapon_link_v2 was changed for an item_link_v2
The base_model key was removed for the new base_variant key on the item response

Item Link V2

This schema now has a permanent boolean is_base_variant key as well as a base_variant and variants key

Technicalities

The base variant of an item is computed by checking its class_name.

Example: Tempo Jacket Silver
This item has the class_name 987_jacket_03_01_02. The last part _02 is removed, and the database is searched for an item having a class_name of 987_jacket_03_01 or 987_jacket_03_01_01.

This seems to work reasonably well, but please let me know if there are any false positives.

kingultron99 commented 4 months ago

so far i've only found A03 "Luckbringer" Sniper Rifle (c98e422d-7380-4c96-b47e-679551699ed4) reporting to be classed as a base variant.

will keep you posted if i stumble across anything else

edit: looking a little more, there appear to be a few weapon variants that have slipped through, only up to 1-2 per weapon, including:

A03 sniper
arrowhead sniper
F55 LMG
C54 SMG
Demeco LMG
FS-9 LMG

I'm also seeing a quickflare in here...? i'll see if i can find more of the quickflares and make another issue for them.