User talk:Eearslya

Feel free to leave any kind of message here for me!

(In)Consistency With Other Pages

I do understand all of the pages added by myself (including the page you changed and that I reverted) are (currently) inconsistent with the stylization of previously created pages; however, those pages can be inaccurate, incorrect, outdated, or misleading in describing/explaining the API and interfacing with it. The previous pages often incorrectly or just fail to indicate data types that should be passed in calls or to be expected in responses; and how to accurately make the calls. They fail accurately and comprehensively list all parameters that can be passed; how to pass them; and, in-general, the manner in which to use them. Etc. I am writing in an industry accepted standard that provides a more comprehensive explanation than what has been previously provided. When time permits, I will also be reviewing and revising past written pages; so that eventually all pages will be consistent and provide correct, accurate, current information. Also, I do watch and monitor the GitHub for the Anet CDI and am current on the most accurate and up-to-date information regarding the API. The API has, in-fact, left the Wiki woefully behind and I have begun to reconcile the two.

If you want to add additional information, upgrade existing information, or fix outdated here and there; I would agree with that. The total removal and mass deletion of information without first discussing the action on the talk page of an article and/or including an editor in the discussion is not an action I can agree with. If you would like to assist in reviewing, revising, and updating the API sections; help is always appreciated. Bandlero (talk) 08:45, 29 July 2016 (UTC)

Alright, I will admit I was a little too overzealous in trying to return the page to the format I was familiar with. For a while, I was the main editor of the API namespace, keeping it up-to-date with the changes, but my work ended up getting in the way. But let me explain myself, and then we can hopefully reach a middle ground going forward.

The term "endpoint" when dealing with query parameters seems confusing to me, since the entire page itself is meant to be describing an API endpoint, this should probably be standardized into "parameters". The reason I omitted the id, ids, and page parameters, is because the endpoint pagination is described on API:2, though I admit right now there's no indication on the wiki of whether an endpoint is paginated or not. We should probably, at the least, include a link to API:2#Accessing_resources. The inclusion of "default/null" values is also somewhat misleading, as most of these values will never be null (and if they are, it's a serious bug). There are some values that can be null (selected traits, inventory slots), but not all.

I would agree the terms "endpoint" and "parameter" can have a lot of interpretations. Endpoint is probably most correctly understood of the two; end points are final destinations or points of calling. Parameter is, in my opinion, not the least troublesome term to be used when describing or dealing with query strings in comparison to endpoints. If it were completely up to me, I would retain endpoint and replace parameter with query string; probably more appropriate too since we're dealing with making HTTP Rest-like API requests. Of course, to play both sides, endpoints in the usage of this API would be more aptly named "paths;" so "endpoint path" when dealing with, for example, v2/finishers/id. I guess I see it as an endpoint is an endpoint regardless if it is "main" or "sub," "child" or "parent," "root" or "path."

Differentiating between the two is, I believe, important as their mutual usage is unbeneficial. Adding a query string/parameter to a child endpoint is, at best, redundant and, at worst, could result in an error or a "not found" result. https://api.guildwars2.com/v2/finishers/1?ids=1 returns the same result as https://api.guildwars2.com/v2/finishers/1. However, neither of those two return the same result as https://api.guildwars2.com/v2/finishers?ids=1. The former calls return a singular JSON object, while the latter returns a JSON object array. That difference in the manner in which data is returned is very important to know/note; an object is not the same as an array of objects. On the matter of the other parameters, pretty much the same redundancy and potential erred results issues arise when using them on a child endpoint. Parameters are intended/designed to be used exclusively on a parent endpoint (or more likely to give people options.) Also, calls made with parameters do not behave or return data the same way as calls to an endpoint; i.e. pagination.

Yes, not every endpoint uses or accepts the same parameters. This (past) lack of consistency in design and implementation in the API can cause problems and confusion. I believe it is best to be thorough in documenting each endpoint instead of just having an addendum that states "you may or may not be able to use X Parameter on the endpoints in this API." If endpoint X accepts Y; it should be stated at so. If endpoint A does not accept B, there should not be another page somewhere that indicates that A might accept B. This definitely would apply more to page_size and page and to a lesser degree ids; not all pages accept any or all of those parameters. I do believe lang is the only parameter universally accepted; though not always useful to pass.

There are cases where values are null; I think we've both probably seen some of the same results and different results as well. As to that being a bug, error, intentional design, or whatever; they do exist in the returned data a lot. Occasionally I see a true null (nothing) result. More commonly, across at least 30% of the endpoints, I have seen "default" null data; for example, zeroes (0) in integer values when no other value was available/provided. This happens also, a lot, with string values in items that have optional descriptions, no icons, or generally just nothing in that string value; sometimes it is an empty string (""), but sometimes it is nothing ( ). Pseudo-null values do arise when an endpoint serves an empty array; you have a data object (the array) it just contains nothing - a cookie jar with no cookies. Yes, I would agree, we should never be getting served default/null values unless default/null data is intended; but when developing for the API it is essential to know the default/null values so that you can anticipate them and program for them. Program for best practices and worst cases. Bandlero (talk) 13:29, 29 July 2016 (UTC)