Announcing WOWAPI and APIMASH - free Starter Kits for your Windows Store Apps
Via DaveDev.net…
Over the course of the past few weeks my team has been hard at work on creating a bunch of Starter Kits in response to the questions we had been getting from Windows Store developers. In particular these Kits focus on calling open web API’s for numerous services and wrap them into workable sample apps. There are a bunch of samples written in both WinJS and XAML/C# for you to take advantage of when building your own apps. All of this code is open source and available right now on Github for you to use in your own apps!
For a great example of a XAML/C# version check out Bob Familiar’s overview of the Rotten Tomatoes Starter Kit here.
World of Warcraft API Starter Kit for Windows Store Apps
Working with HTML5 and JavaScript developers the past year I’ve been using my Windows 8 Game Kit (Git version here) as an instructional tool and way to bootstrap your own Windows Store games. One of the areas I purposely left out however was web service calls. For the APIMASH project I wanted to create a new kit that was easy to follow and focused just on wrapping some of these web service calls into a sample app.
I chose to use Blizzard’s World of WarCraft APIs for the sample app to display Realm Status (these are the game servers for World of Warcraft). For those not in the know World of Warcraft is a very successful online game from Blizzard Entertainment® and offers an excellent open api to get game statistics. The full API documentation can be found at https://blizzard.github.io/api-wow-docs/.
Currently I have implemented the WOW API into three core pieces of functionality.
- Realm Status (individual)
- Realm Status (all)
- Localization (results from WOW API can be returned in en_US, es_MX, or pt_BR)
I wanted the Windows Store App to also serve as a workable app template for helping your own apps pass certification. Taken what I’ve learned from my own apps I’ve implemented several pieces of functionality I’ve seen developers fail certification on or get tripped up with during development. This sample app includes workable functionality for all of the following:
- Application Bar (For Language Localization settings)
- Share Contract (Share at any time from any of the pages)
- Settings and Privacy Panel
- Icons (Sample Icon and Images)
- Roaming Settings (Localization settings are stored in the users roaming settings)
- Scaling (App uses a ViewBox control to scale up on screens larger than 1366x768)
Requirements
- Windows 8
- Visual Studio 2012 Express for Windows 8 or higher
Setup
- Download the Starter Kit Zip Portfolio from (https://apimash.github.io/StarterKits/)
- Open the Solution in Visual Studio
- Compile and Run
Customization
Step 1. All of the Blizzard World of Warcraft API's do not require a developer key to use. However, if you plan on creating an application with heavy api usage Blizzard requests you contact them at api-support@blizzard.com to register your application.
Step 2. Currently only Realm Status is implemented. Adding additional functionality such as character or pvp info is as easy as calling the appropriate wow api (found in https://blizzard.github.io/api-wow-docs/) and then wrapping it in a function the same way realm status was done in /js/wowapi.js.
(function () {
"use strict";
var supported_locales = ["en_US", "es_MX", "pt_BR"]; //US Battle Realms
var _locale;
WinJS.Namespace.define("wowapi", {
realmStatusToColor: WinJS.Binding.converter(function (status) {
return status == true ? "green" : "red";
}),
realmStatusToText: WinJS.Binding.converter(function (status) {
return status == true ? "UP" : "DOWN";
}),
checkLocale: function (locale) {
return $.inArray(locale, supported_locales) == -1 ? "en_US" : locale;
},
getRealmStatusAll: function (locale) {
return new WinJS.Promise (function (complete)
{
_locale = wowapi.checkLocale(locale);
var _result = {};
WinJS.xhr({ url: "https://us.battle.net/api/wow/realm/status?locale=" + _locale, responseType: "json" }).then(
function (response) {
var json = JSON.parse(response.responseText);
complete(json.realms);
});
});
},
getRealmStatus: function (realm, locale) {
_locale = wowapi.checkLocale(locale);
WinJS.xhr({ url: "https://us.battle.net/api/wow/realm/status?realm=" + realm + "&locale=" + _locale, responseType: "json" }).then(
function (response) {
var json = JSON.parse(response.responseText);
//var serverList = new WinJS.Binding.List(json.realms);
//var lv = document.querySelector("#servers").winControl;
//lv.itemDataSource = serverList.dataSource;
//lv.itemTemplate = document.querySelector("#servertemplate");
//WinJS.UI.processAll();
return json.realms;
},
function (error) { WinJS.log(error); },
function (progress) { }
)},
getRealms: function (locale) {
_locale = wowapi.checkLocale(locale);
WinJS.xhr({ url: "https://us.battle.net/api/wow/realm/status?locale=" + _locale, responseType: "json" }).then(
function (response) {
var json = JSON.parse(response.responseText);
var serverList = new WinJS.Binding.List(json.realms);
return serverList;
},
function (error) { WinJS.log(error); },
function (progress) { }
)},
})
})();
The wowapi.js file is a single enclosed JavaScript function with top half of being two data converter functions to show realm status as color or text versus Boolean values. The Realm Status functions are using WinJS XHR calls wrapped as a WinJS Promise. By using a JavaScript Promise we are able to have our UI wait for a response from the web service calls before binding the results to a ListView.
getRealmStatusAll: function (locale) {
return new WinJS.Promise (function (complete)
{
_locale = wowapi.checkLocale(locale);
var _result = {};
WinJS.xhr({ url: "https://us.battle.net/api/wow/realm/status?locale=" + _locale, responseType: "json" }).then(
function (response) {
var json = JSON.parse(response.responseText);
complete(json.realms);
});
});
},
This also allows us to separate our concerns with all of the WOW API’s wrapped inside of wowapi.js and then the specific UI databinding code being stored in the individual WinJS Page controls.
Step 3. Once you have data returning you should bind to a listview in the same manner /realmstatus/realmstatus.js currently is.
//Get All Realms
wowapi.getRealmStatusAll(app.sessionState.locale).then(function (realms) {
var realmsList = new WinJS.Binding.List(realms);
var lv = document.querySelector("#servers").winControl;
lv.itemDataSource = realmsList.dataSource;
lv.itemTemplate = document.querySelector("#servertemplate");
WinJS.UI.processAll();
});
The data converters are optional I am simply changing the background color style of the individual elements in the Listview’s Template based on weather the Realm is currently online or not.
<div id="servertemplate" data-win-control="WinJS.Binding.Template">
<div data-win-bind="style.backgroundColor: status wowapi.realmStatusToColor">
<h3 id="name" data-win-bind="innerText:name"></h3>
</div>
</div>
<div class="headertemplate" data-win-control="WinJS.Binding.Template">
<div id="headername" data-win-bind="innerText.style.color: status wowapi.realmStatusToColor; innerText:status wowapi.realmStatusToText"></div>
</div>
<div id="servers" data-win-control="WinJS.UI.ListView"></div>
Step 4. I highly recommend you use WinJS Page controls to follow standard convention. Simply create a new folder in the root of the project, right click and add a new "Page Control". Then edit the html, css, and js in the same manner that was done in the /realmstatus page control.
That’s it! You now have a fully functional Windows Store app that is generating data from Web Service calls to Blizzard’s WoW API.
Conclusion
Hopefully these Starter Kits will help aid you in your own Windows Store app development. If you live within the Philadelphia, PA area I have been running a Philly Appathon Workshop series that covers the APIMASH Starter Kits as well as a developer topic each week. We are now in the fifth week and will be wrapping up but if you have missed any of the contest I have posted everything online on my slideshare. I will continue to be available through my office hours as well as at the Philly App Labs and monthly meetings. So if you are a local Pennsylvania developer looking for some Windows Store or Windows Phone app assistance please introduce yourself!
For those not in the local are my team will also be running a Webcast Series. Each session will run from Noon – 1pm EDT. Attend one or all four webcasts, you decide. For more details or to register, choose a webcast below.
6/5/2013 | Exploring the Mashery APIs
In this webcast you will learn how to develop Windows 8 apps using Mashery API’s such as Tom-Tom, Edmunds, Rotten Tomatoes and Active.com. Amit Jotwani from Mashery will join us to provide an overview of Mashery the industry leader in API management. We will cover how to access these web service API’s and then deserialize the response into a set of runtime objects that you can bind to Windows 8 UX Controls to create a compelling experience.6/12/2013 | Exploring the Social Networking APIs
In this webcast you will learn how to develop Windows 8 apps using the Twitter, Meetup and Facebook APIs. Twitter, Meetup and Facebook are the premier social networking sites and their API’s provide access to Tweets, Meetups and Friends. What a great combination!6/19/2013 | Exploring the Yelp API
In this webcast you will learn how to develop Windows 8 apps using the Yelp API. Yelp is a local business directory service and review site with social networking features. People use Yelp to search for everything from the city’s tastiest burger to the most renowned cardiologist.6/25/2013 | Exploring the Bing Maps API
In this webcast you will learn how to develop Windows 8 apps using the Bing Maps API. Bing Maps gives you a rich set of tools to help you create amazing map experiences perfect for mash-ups.
Lastly don’t forget to check out the “Keep the Cash Rewards” offer to see how you can get $100 for publishing your app(s) in the Windows Store and/or Windows Phone Store. Publish your app before June 30, 2013 and you can get a $100 virtual Visa card for every qualified app you enter (up to $2000*). Learn more.
-Dave