Comunity Platform API Feedback

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.