Guild Wars 2 API Wrapper Library

June 21, 2017
Source
Motivation

To be honest, making this library was never on the table for me. Yet, here I am with a library, which covers over a hundred Guild Wars 2 API endpoints. The turns of events that caused me to create this library is truly unfortunate. See, back when I was planning to create an android companion application, I knew there is a list of Guild Wars 2 API Wrapper on the Guild Wars 2 official wiki and I found one that is made for Java. I knew the difference between android and Java might cause me unable to use that library. So, I create a simple unit test to see if that library will work in android environment, I thought it was working. Thus, I go on implementing my android application without worrying much about the API wrapper library.

However, when I was at the point where I need that library to access the API, I learned that I was wrong about the library. It wasn’t working, it uses javax, it probably will never work in android environment. At that time, I thought I have other libraries to use. But no, all other libraries are way too outdated for me to use. So, I was faced with three choices, somehow put javax API in my app, abandon the app, or make my own wrapper library. Putting javax in my app will bog it down too much, therefore that is not a choice. Abandoning it is the easiest way to go, however there is no way I’m abandon a project, so that is out of picture as well. Thus, the only choice I’m left with is to create my own library that will work for android. And that is how I create a Guild Wars 2 API wrapper library. Since I don’t want other people to go through what I went through, I released my library on both JCenter and Maven Central.

Overview

This library grants user access to Guild Wars 2 HTTP API without the need to implement any underlying structures. The library uses Retrofit 2 as a HTTP client to connect with the API and JSON reply from the API is parsed using Gson converter.

How To Use
Note: when using this library in Android application make sure to require internet permission 
<uses-permission android:name="android.permission.INTERNET"/>
First of all, you need to get GuildWars2 object by calling: 
GuildWars2.getInstance();
Use methods in SynchronousRequest class to get the content synchronously, which can be accessed by calling getSynchronous() function in GuildWars2 class. For instance, to get content of item 12452 and 28445 synchronously:
GuildWars2 api = GuildWars2.getInstance();
int[] ids = new int[]{12452, 28445};
List<Item> result = api.getSynchronous().getItemInfo(ids);
//more amazing codes
Use methods in AsynchronousRequest class to process you the content asynchronously, which can be accessed by calling getAsynchronous() function in GuildWars2 class. For instance, to process content of item [12452 and 28445 asynchronously: 
GuildWars2 api = GuildWars2.getInstance();
int[] ids = new int[]{12452, 28445};
api.getAsynchronous().getItemInfo(ids, new Callback<List<Item>>() {
  @Override
  public void onResponse(Call<List<Item>> call, Response<List<Item>> response) {
    //more amazing codes
  }

  @Override
  public void onFailure(Call<List<Item>> call, Throwable t) {
    //handle failure
  }
});
Data Classes
Each content model class follows the exact same format presented by official wiki. Thus a good way to know what to expect from a model class is to go to the API wiki page and see what is in the response for that endpoint. For example, the response for /v2/tokeninfo:
  • id (string) - The API key that was requested.
  • name (string) - The name given to the API key by the account owner. Warning: The value of this field is not escaped and may contain valid HTML, JavaScript, other code. Handle with care.
  • permissions (array) - Array of strings describing which permissions the API key has.
The format for TokenInfo class is: 
public class TokenInfo {
  private String id;
  private String name;
  private String[] permissions;
  //getters
}
Note: If parts of response of an endpoint is not documented on the wiki, I probably will missed it in my model class. So if you see anything I missed, please don't hesitate to create an issue to let me know.