Talk:WebAPI/Feedback

From Team Fortress Wiki
< Talk:WebAPI
Revision as of 18:23, 23 November 2010 by Joe (talk | contribs) (Versioning)
Jump to: navigation, search

Suggestions

Things that should be fixed in the Steam Web API system

  • JSON and VDF should use arrays rather than objects containing arrays. Having them structured differently from XML complicates code unnecessarily (and result.items.item[1] is redundant compared to results.items[1]). This seems to have been designed to preserve the element name used for the individual objects in XML (allowing multiple arrays to be defined in the event of mixed types, which should be structured as multiple arrays in XML as well). When everything in an array is of the same class, nobody in JSON cares about that class's name (only its index in the containing array, and anybody using VDF is using code that was written for the original data file, which is structured this way.

Short version: this

 "result": {
   "status": 1,
   "items": {
     "item": [
       {
         "id": 18446744073709019323,
         "defindex": 125,
         "level": 1,
         "quality": 3,
         "inventory": 2149580806,
         "quantity": 1
       },
       {
         "id": 1029705,
         "defindex": 36,
         "level": 5,
         "quality": 3,
         "inventory": 2147483655,
         "quantity": 1
       },
     ]
   }
 }

should look like this:

 "result": {
   "status": 1,
   "items": [
     {
       "id": 18446744073709019323,
       "defindex": 125,
       "level": 1,
       "quality": 3,
       "inventory": 2149580806,
       "quantity": 1
     },
     {
       "id": 1029705,
       "defindex": 36,
       "level": 5,
       "quality": 3,
       "inventory": 2147483655,
       "quantity": 1
     },
   ]
 }

--STUART 04:23, 5 July 2010 (UTC)

Methods that should be added to ITFItems_440

  • A method that returns all of a language's strings for a given language (like resource/tf_english.txt). This would allow simpler caching of GetSchema with regards to translation (clients would only need 1 GetSchema return for all languages, and could request each language individually without needing to get all of the schema data again, increasing the signal:noise ratio significantly for translation). --STUART 04:22, 5 July 2010 (UTC)
  • A method that returns the latest revision information for each of these, so systems know when they need to make the heavy call to GetSchema and other static methods. --STUART 04:22, 5 July 2010 (UTC)
  • A method that returns inventory images, or links to images. Currently the biggest hurdle of an update is digging all of the new data out of the tf2 gcfs. The three files at the moment are: items_game (partially covered by the GetSchema), tf_<lang> (Partially covered by GetSchema), and the backpack images (No solution). The images are also the most time consuming part. FireSlash 17:02, 5 July 2010 (UTC)
Biggest hurdle? Extract tf/materials/backpack and run it through VTFEdit's batch converter. Netshroud 23:27, 5 July 2010 (UTC)
As far as time consumption yes, since I also need tor resize and recompress images. items_game and tf_english are just a matter of extracting and uploading each file. Where in the images I have to sort through all the images in the gcf, dig out the new ones, extract convert resize and upload. If the images were available online, I could automate the process. FireSlash 00:58, 6 July 2010 (UTC)

Things that should be added to the next version of GetSchema

  • The revision number, so systems can compare it (for stored data) against the latest revision (as described above). --STUART 04:22, 5 July 2010 (UTC)
  • The defindex of attributes for items, rather than the attribute's name and class. If GetPlayerInventory uses defindex for its attributes, GetSchema should too. --STUART 04:22, 5 July 2010 (UTC)
  • Add missing fields used_by_classes and craft_class FireSlash 16:17, 5 July 2010 (UTC)
  • Add field propername to allow for simple construction of item name. i.e "A <Community> __" vs "The __", and "The Hound Dog" vs "Hound Dog". Ath 14:27, 12 August 2010 (UTC)
  • Descriptions for the items would be very much appreciated. Netham45 18:39, 10 October 2010 (UTC)

Things that should change in future versions of GetPlayerInventory

  • Ditch the "quantity" field. With a unique ID on the item, how can this be anything but 1? --STUART 04:22, 5 July 2010 (UTC)
  • Separate the "inventory" field into an "inventory_slot" value and "equipped" object (with a "true" for each class the item is equipped for, and empty if no classes have the item equipped). This is a Web API: consumers shouldn't have to do binary operations to parse it. --STUART 04:22, 5 July 2010 (UTC)
  • Add a "timestamp" field, similar to the GetGoldenWrenches method. This would be useful for statistics and curiosity of users. --AltPluzF4 11:44, 10 July 2010 (UTC)

Alternative WebAPI profile query methods

  • Allow developers to pass a vanity URL "ID" as an arguement to the WebAPI or more easily convert a vanity URL to a SteamID64. The Steam Community XML feed breaks easily and does not properly sanitise community-side user input. (I.e. Non-UTF8 characters present in feed) Ath 23:18, 10 August 2010 (UTC)
One thing you could do until this happens is just search for the tag without passing it to a full parser. It's less lines of code and works regardless of encoding on the rest of the page. This is what I do in steamodd, and this way you only have to rely on the tag name not changing. Lagg 10:35, 11 August 2010 (UTC)
I make use of other parts of the XML too (May as well if I have to fetch it anyway :( ), so passing it to PHP's SimpleXML lib (through utf8_encode first) is simple and effective enough I find. Thanks for the suggestion though. Ath 14:27, 11 August 2010 (UTC)

Problems

Breaking GetPlayerItems Bug

With certain backpacks (for example, 76561197967454254, one of the PCGamer employees) there appears to be a floating point error inserted into attribute values without being checked before hand. This results in invalid JSON that most parsers will fail on.

Example:

							{
								"defindex": 127,
								"value": 4294967294,
								"float_value": -1.#QNAN0
							},

-- Lagg Backpack Stickybomb Launcher.png 09:43, 10 November 2010 (UTC)

Oh joy. Glad to see serious issues like negative IDs were fixed though! Ath 19:42, 10 November 2010 (UTC)
The next update fixes this by not providing a float_value for values that are invalid. Long term I intend to provide more useful output for attributes than their raw value, especially in the case of particle effects like this one. Joe 23:33, 17 November 2010 (UTC)

Invalid Encoding in Certain Item Names, Descriptions, Personas, and Real Names

It appears that custom item names, descriptions, and community profile names and personas (and probably anything else that takes user input) isn't being sanitized before the JSON is generated. Invalid character encoding is also invalid JSON. -- Lagg Backpack Stickybomb Launcher.png 19:50, 10 November 2010 (UTC)

If you see an example of an account with a custom item name or description that's broken in this way, please post it here. I believe that there's a bug in our encoding of names somewhere, I just need a repro case. Joe 23:31, 17 November 2010 (UTC)
Joe, would it be possible for you to grant either myself or Lagg a name/desctag to attempt to repro this? I had a report of an effected profile, but it's no longer exhibiting any issues. Thanks. Ath 23:35, 17 November 2010 (UTC)

List of Problematic Attributes

Please feel free to edit or correct this list if I missed anything (I want to keep it all here to be more visible to Joe) -- Lagg Backpack Stickybomb Launcher.png 03:57, 14 November 2010 (UTC)

Attributes with no description string
27 alt-fire disabled
29 alt-fire is vampire
43 scattergun no reload single
53 fire retardent
116 mod soldier buff type
117 dmg falloff increased
122 mod demo buff type
167 disguise damage reduction
183 aiming movespeed decreased
184 duel loser account id
189 elevate quality
Attributes with undefined description_string
192 referenced item id low
193 referenced item id high
Attributes with incorrect description strings
195 always tradable
196 noise maker
144 lunchbox adds minicrits
Attributes attached to items they shouldn't be attached to
144 lunchbox adds minicrits (attached to the GRU)
The behavior on referenced_item_id_* is intentional. These are hidden attributes, so they don't have a description. Some of the others that have the wrong descriptions are also hidden and need their descriptions removed. The next webAPI update (which will happen soon) adds the hidden flag to what is provided for attributes, so it's easier to detect these attributes. I'll look at the others. -- Joe 22:20, 15 November 2010 (UTC)
Great, but I strongly suggest setting description_string to null or an empty string on those attributes. Otherwise I need to mark it as optional in the docs. -- Lagg Backpack Stickybomb Launcher.png 01:46, 16 November 2010 (UTC)
These are fixed as of the next update. Hidden attributes now never return a description_string or description_format field. I'll update the docs to reflect that when the update goes live. There are still a couple of unused attributes (alt-fire disabled and alt-fire is vampire, for instance) that don't have strings. If we ever use them for anything they will get strings at that point. Joe 23:29, 17 November 2010 (UTC)
Alright, most of these appear to be fixed but some of the hidden/unused ones still have the description token there instead of being empty. It doesn't matter at this point though since we have the hidden flag now (Many thanks, Joe). However the GRU still have the minicrit attribute attached, not sure if this is intentional (See here). -- Lagg Backpack Stickybomb Launcher.png 02:53, 20 November 2010 (UTC)
It's intentional. The name is poor, but since the attributes are hidden and the name never shows up anywhere but the webapi it hasn't been a big priority to change. Joe 02:54, 20 November 2010 (UTC)

Versioning

What's the point of having the potential for versioning (e.g. GetSchema/v0001) if it's not used? The recent update (November 20) removed description_format and desciprion_string from a whole handful of attributes, in turn breaking my iOS application. I was saving data out to Core Data and had the description format and description string as required attributes for the backpack item attribute. Missing required attributes caused the application to crash when saving the data. This has since been patched and the fix has been uploaded to the App Store, but typical review times are a week. I've requested an expedited review, but nonetheless the latest API update broke my application which was essentially using the API in the way it was intended. Please version major changes such as removal of fields (or making them optional), or at least provide some advance warning. Netshroud 07:48, 21 November 2010 (UTC)

I didn't roll the version number because I didn't consider the changes significant enough to warrant a version number change. I underestimated the impact they would have, obviously. Almost all of the API changes so far have been additional fields, so it hasn't been a problem.
What do other people using the webapi think about version number changes? Would you like to see updates roll the version number every time and leave the old version in place for a while? (At least for updates that change the web api. That's many of them, but not all of them.)
The safest way to use this (or any other web api for that matter) would be to treat most fields as optional. Particularly fields in attribute types and item types are likely to be present on only some types. That advice is a little too late to be helpful in this case though.
Joe 18:23, 23 November 2010 (UTC)

Values

float_value never matches value. In some cases (e.g. Mann Co. Supply Crates), float_value is correct and value is completely wrong. In other cases (e.g. Employee Badges), value is correct and float_value is way out. Netshroud 07:48, 21 November 2010 (UTC)