How to fetch new community APIs?

API Discussion
I believe your new documentation is incomplete, to put it kindly.

I want to load the information for WoW achievement 2144. What URL do I use?

This page says the endpoint is /wow/achievement/:id
https://develop.battle.net/documentation/api-reference/wow-community-api

The migration guide says the new host is us.api.blizzard.com
https://develop.battle.net/documentation/guides/migration-guide

It also says that, "Community API requests only require a client ID."

This page says, "For authentication instructions and implementation details, see Using OAuth."
https://develop.battle.net/documentation/guides/community-apis

The OAuth page just talks about "allow Blizzard to handle authentication and receive a unique user ID, then use an access token for allowed resources like World of Warcraft characters, StarCraft II profile data, or other information as appropriate."
https://develop.battle.net/documentation/guides/using-oauth
I don't care about authenticating a player, I just want info on an achievement.

There are no useful error messages. https://us.api.blizzard.com/wow/achievement/2144 just says "404 Not Found" with no response body.

I registered for new client ID. Where do I put it? What's the URL argument or header name? Where was this information in the documentation?
Ditto this big time for more info on what migrating existing applications looks like for existing Community APIs that use an API key (not OAuth / Game Data APIs).
Actually, for me the biggest obstacle was understanding the difference between (*) client credentials flow and that other oauth thing that requires a https callback url, which can be painful to set up in a local environment.

Just getting data from the api isn't really that different. It's just two requests instead of one, and if you cache the token, it's still only one.

(*) Just imagine a large pause here while I'm searching the documentation for something to copy and paste... Apparently the "other" thing is called "Authorization code server flow". Maybe it could be useful to include a short newbie chapter on what kind of flow is needed for what kind of application. Something like: "Unless you want to query player profiles, all you need is client id and client secret"
Greetings Erorus,

Thanks for your feedback! We value hearing from our community as we strive to constantly improve.

To address some of your points:

Request Authorization

Last year when we introduced the suite of APIs commonly refered to as the "Game Data APIs", Blizzard also added support for the OAuth2 client credentials flow, which first requires a consumer to obtain a Access Token before making requests.

As we move over to the new developer portal (develop.blizard.com) and the new API Gateway (us.api.blizzard.com, etc), all requests to resources exposed through Blizzard APIs will require the use of a OAuth2 access token which was obtained either through the Client Credentials flow, or the Code Authorization Flow.

An example of obtaining an access token through the Client Credential Flow can be seen below:

Requesting an access token:

curl -u {client_id}:{client_secret} -d grant_type=client_credentials https://us.battle.net/oauth/token

Authorizing a request with a access token:

curl -H "Authorization: Bearer {access_token}" https://us.api.blizzard.com/wow/achievement/2144

Please review the Client Credentials Flow guide for more examples. Also, the Using OAuth guide, under the Using an access token heading, contains additional examples for usage of the acess token via an Authorization Header.

Error Messages for Achievement 2144

This issue was previously identified and is now resolved. Please see this related thread.

We look forward to your success, and please do let us know about any further feedback!

Thanks!
10/02/2018 03:59 PMPosted by Maguthul
Please review the [url="https://develop.battle.net/documentation/guides/using-oauth/client-credentials-flow"]Client Credentials Flow guide[/url] for more examples. Also, the [url="https://develop.battle.net/documentation/guides/using-oauth"]Using OAuth guide[/url], under the Using an access token heading, contains additional examples for usage of the acess token via an Authorization Header.

Thanks for your reply. I think I see where I got confused.

On your migration guide at https://develop.battle.net/documentation/guides/migration-guide you have this:
Blizzard API requests require client credentials for different types of requests:

Community API requests only require a client ID.
Game Data API requests also require an access token acquired via the client credentials flow.

That makes it sound like the Community API requests and Game Data API requests are authenticated in different ways. (And so I scrambled thru your documentation looking for what makes Community different.) Your reply above tells me that Community API requests follow the client credentials flow the same as Game Data API requests.

Please update your migration guide to say that Community API and Game Data API requests are authenticated the same way. You can also include that the Game Data API flow is mostly the same as it was on Mashery, and it's Community API that was changed from the Mashery way to match Game Data API.
This url works here, https://us.api.battle.net/wow/character/bleeding%20hollow/desolari?fields=achievements&locale=en_US&apikey=removed,
when posting to fiddler.

Yet the url you provide, https://us.api.blizzard.com/wow/achievement/2144,
works correctly with the Bearer token I am still confizzled as to why you didn't do a 302 resource moved with the us.api.battle.net urls instead of giving me a false positive that this url still works?

I understand it is difficult work but this is why there is a version number in the header. It is so your apis are backwards compatible.

Update docs required.
This url works here, https://us.api.battle.net/wow/character/bleeding%20hollow/desolari?fields=achievements&locale=en_US&apikey=removed,
when posting to fiddler.

Yet the url you provide, https://us.api.blizzard.com/wow/achievement/2144,
works correctly with the Bearer token I am still confizzled as to why you didn't do a 302 resource moved with the us.api.battle.net urls instead of giving me a false positive that this url still works?

I understand it is difficult work but this is why there is a version number in the header. It is so your apis are backwards compatible.

Update docs required.


The code required, which gives failures and false positives vs. 304 redirect or [Obsolete] or 302 moved of any sort. See catch statement.

[TestMethod]
public async Task GetWowNewNew()
{
HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer obfuscated");

var newWay = "https://us.api.blizzard.com/wow/achievement/2144";

var Name = "Desolari";
var Realm = "bleeding%20hollow";

var wowRequestUrl =
String.Format(
"https://us.api.battle.net/wow/character/{1}/{0}?fields=achievements&locale=en_US",
HttpUtility.UrlEncode(Name), Realm);

var result = await client.GetStringAsync(newWay);
Assert.IsNotNull(result);

try
{
// breaks but has the same headers
var resultOld = await client.GetStringAsync(wowRequestUrl);
}
catch(Exception ex)
{
Assert.IsNotNull(ex.InnerException);
}

}
Looks like the API changed again. C'est la vie.

Join the Conversation

Return to Forum