There does not apear to be a dedicated thread for general Comunity Platform API feedback, so I thought I would start one. Only Grotako’s thread is more general in nature http://us.battle.net/wow/en/forum/topic/2516991705 , but that is limited to the Character, Guild and Arena API’s.
Now for some feedback. Let’s take a look at the URL buildup for the different API’s.
Realm Status API
http://{region}.battle.net/api/wow/realm/status?realm={realm_name}
| |_________________| |_____| |__________| |________________|
| | | | |
scheme[1] domain[2] api[3] api-path[4] parameter[5]
Character API
http://{region}.battle.net/api/wow/character/{realm}/{name}?fields={CSV}
| |_________________| |_____| |______________________| |__________|
| | | | |
scheme[1] domain[2] api[3] api-path[4] parameter[5]
Guild API
http://{region}.battle.net/api/wow/guild/{realm}/{name}?fields={CSV}
| |_________________| |_____| |__________________| |__________|
| | | | |
scheme[1] domain[2] api[3] api-path[4] parameter[5]
Arena API
http://{region}.battle.net/api/wow/character/{realm}/{size}/{name}?fields={CSV}
| |_________________| |_____| |_____________________________| |__________|
| | | | |
scheme[1] domain[2] api[3] api-path[4] parameter[5]
As we can see part [1] [2] and [3] of the URL buildup are concise. Part [3] and [4] make up the path of the URL, with part [4] having a different makeup depending on the API being called. Part [5] consists of a query.
Consistancy
The API’s mentioned here can be split into two groups when looking at URL buildup; the Realm Status API and the other API’s. The Realm Status API does not contain any variable information in it’s path [4]. The other API’s do contain variables in their paths. What at first seems like an inconsistency is actually a well thought out design. The goal here was to have the base URL (part [1] through [4]) contain the bare minimum of information necessary for each individual API to return a default payload. Additional parameters [5] can be added to each of the API URL’s to narrow down or to expand upon the information returned by the targeted API.
What I do find confusing however is the difference in the query-string [5] buildup between the Realm Status API and the other API’s. The Realm Status API has a traditional build up where the realm parameter can be repeated thus:
?realm={realm_name}&realm={realm_name}&realm={realm_name}
Whereas the Other API’s consist of one parameter (fields) which can hold comma separated values, like so:
?fields={CSV}
Why not also have the Realm Status API reflect parameter usage in the same manner and have realms be a single parameter with comma separated values?
?realms={CSV}
Validation
The API payload is a JSON format and since there is not yet a JSON schema language approved by a standards body, validating the payload is not a given. The old armory had an XML payload and no schema attached to it (at least not to the outside world), but the hierarchy and makeup of the payload did change over time. Keeping up with those changes without schema validation was a challenge.
To not have history repeat itself I would like to suggest the use of Orderly ( http://orderly-json.org/ ) or a similar library to compile JSONSchema’s. (I really love the idea of schema’s that are defined in the same language that they are validating, just like XML) Those schema’s can then be made public through the API URL like so:
http://{region}.battle.net/api/wow/realm/status/schema
http://{region}.battle.net/api/wow/character/schema
http://{region}.battle.net/api/wow/guild/schema
http://{region}.battle.net/api/wow/character/schema
In keeping with the design of the current API’s, the above mentioned URL’s would return the latest version of a schema. Older schema’s can be returned with an aditional parameter:
?version={version}
This alone would help tremendous amounts towards building fault-tolerant systems that consume the Comunity Platform API’s. The addition of the schema version in the payload would be an added bonus, but certainly not a necessity.
{
"schema":"v1.2",
"realms":[
{
"type":"pvp",
"queue":false,
"status":true,
"population":"medium",
"name":"Dunemaul",
"slug":"dunemaul"
}
]
}
EDIT: Many changes.
|
|
|
Following is taken from http://us.battle.net/api/wow/realm/status?realm=Medivh&realm=Dunemaul
{ "realms":[ { "type":"pvp", "queue":false, "status":true, "population":"medium", "name":"Dunemaul", "slug":"dunemaul" }, { "type":"pve", "queue":false, "status":true, "population":"medium", "name":"Medivh", "slug":"medivh" } ] } The example above contains 302 characters, 340 bytes and 20 lines. Of which 92 characters are spaces (45 per realm entry), 19 characters are carriage returns and 19 characters are line feeds as illustrated below. {[\r][\n] .."realms":[[\r][\n] ....{[\r][\n]" ......"type":"pvp",[\r][\n] ......"queue":false,[\r][\n] ......"status":true,[\r][\n]" ......"population":"medium",[\r][\n] ......"name":"Dunemaul",[\r][\n] ......"slug":"dunemaul"[\r][\n] ....},[\r][\n]" ....{[\r][\n]" ......"type":"pve",[\r][\n] ......"queue":false,[\r][\n] ......"status":true,[\r][\n] ......"population":"low",[\r][\n] ......"name":"Medivh",[\r][\n] ......"slug":"medivh"[\r][\n] ....}[\r][\n] ..][\r][\n] } Once collapsed/condensed the same information is contained in 210 characters, 210 bytes and of course 1 line. That is a net gain of a little over 38% ((340-210)/340*100) compared to the original byte size. JSON suffers from the same dramatic inflation that all hierarchical based notations do; it gets exponentially worse the more nested the data is. With the upcoming API’s where data becomes more nested I can see that number going way up. Al the disadvantages of the redundant overhead are quite apparent. The advantage is also quite apparent: a more human friendly readable form. That is why I would like to plead for an additional parameter on all API URL’s with a JSON payload with which the overhead can be toggled on or off. Something along the lines of a boolean ‘collapse’ which can be set to ‘true’ or ‘false’. I would also recommend to have the payload be collapsed by default. *EDIT*: typo |
|
What a journey to get this bug to the right people. I am originally a EU player and found a bug while making Java wrapper library for the new API (btw kudos on that, love the new API). Posted on the EU forums ( http://eu.battle.net/wow/en/forum/topic/2123512342 ) to no avail. Mailed to the people of the US support team who misunderstood me and were so kind as to redirect me to specific US forums to post in... In a last attempt, I bought a US license and leveled a char so I could post on these forums. Hard work to get a bug where it’s supposed to go, but got there in the end! :) /cheer
Now for the bug. When checking the headers for the new Realm status API I noticed that the Content-Type header has the correct MIME-type but the wrong character encoding. The Content-Type header has the value of application/json;charset=ISO-8859-1. As you can see the character encoding is set to ISO-8859-1 (Latin-1). The content itself is UTF-8. This is of course a good thing, we want the content to be UTF-8 encoded. But the charset in the Content-Type header needs to be set accordingly. This might not have been apparent at first because the lower range characters of the ISO-8859-1 set are equal to the lower range characters in UTF-8. However, it becomes plainly apparent with higher range characters (e.g. Cyrillic characters ). If you were to go to the European realm status ( http://eu.battle.net/api/wow/realm/status ) and try to view it in a browser like Chrome, you would see that the server names in Cyrillic look like gibberish. This is because the browser tries to render the characters in the character set found in the Contet-Type header (i.e. ISO-8859-1). So, to make a long story short. Can the value for charset in the Content-Type header be set to UTF-8? |