Exactly, Kevin.
The APIs I run definitely don’t operate on as much data as Blizzard has, nor are they likely used by as many folks, but we try exceedingly hard to ensure they’re logical and straightforward to use.
This API feels like it’s a really thin layer that someone taped on top of a query and decided to ship. I mean, the (giant air quotes) documentation for the connected realms endpoint says, and I quote
Returns an index of connected realms.
That’s it. That’s the documentation, in it’s entirety. That screams auto-generated and ignored. Returns the $parameter of $endpoint.
Okay, fine, not the first time I’ve dealt with bad documentation before.
But the key/href objects in the responses. Which they claim is to “increase discoverability”? That’s what really gets me. Discoverable for who? That is so disconnected from what an API is supposed to be that it’s almost baffling. Like, I have to assume the intent is to do something like the HATEOAS principle behind REST APIs. Except that the intent of that is to have a client that could dynamically dig it’s way through an API by performing named actions on data. Where as these endpoints just respond with “This is a related link!” That’s not actionable, dynamic, or even purposeful really.
Them’s big-time smells, imo. Maybe was there as some part of the development process, to debug that links are working the way they expect, and it was supposed to be more?
Lets take a look at a response even!
{
"_links": {
"self": {
"href": "https://us.api.blizzard.com/data/wow/connected-realm/?namespace=dynamic-us"
}
},
"connected_realms": [
{
"href": "https://us.api.blizzard.com/data/wow/connected-realm/4?namespace=dynamic-us"
},
{
"href": "https://us.api.blizzard.com/data/wow/connected-realm/5?namespace=dynamic-us"
}
}
(trimmed, because I've no need to spam.)
First, you told me the endpoint that I? called? I’m the one who made the call, why are you telling me? Next, connected_realms, okay, that’s a fair name. I did call the connected-realms endpoint… and it’s a bunch of objects with a single key each named href?!
Oh, wait, there’s an interesting header, Battlenet-Schema: connected-realm, okay, a schema, that’ll help. Except… it doesn’t. They’re not documented. They’re not even defined. The intro to the API docs says:
Game data and profile APIs allow Blizzard to share game information via a single, well-defined interface in an easily-consumable format that has an agreed-upon schema between publisher and consumer.
Doesn’t seem that well defined to me. Agreed on by whom?
What if I think, well forget all that, and decide to just call those silly little hrefs anyways! Whoops, another pitfall!
As the World of Warcraft team continues to develop and release new data into the Game Data and Profile APIs for World of Warcraft, there might be times where a JSON response document links to a child JSON document that is:
- protected by a private scope and has not yet been released for public consumption.
- not yet published.
In these cases, a request to the child resource returns a 404, 401, or another appropriate status code and response.
They may not even work. And what’s more than that, they may fail with errors that look like transient or application caused errors! In fact you may end up telling my application that it’s unauthorized to check out the link you just handed it? Seriously? Worse still, 401 implies that authorization is possible! At least use 403 if you want to just slam the door, despite showing me that the door exists.
But here, I’ll give you this bit for free: 405 Method Not Allowed. It’s literally a response code for “I don’t want you to do that.” I’d even not blink at a 503 Service Unavailable, with a Retry-After of next month.
Maybe I’m just becoming more of a curmudgeon in my age, but call me crazy to think I like my APIs to make sense and be approachable.
But my goodness, get an intern to write a few lines of documentation and publish a schema or two.