Data Repositories

Guild Wars 2 API services can be thought of as relational databases.
The GW2.NET library provides access to this relational data through generic data repository interfaces.

If needed, take a moment to familiarize yourself: The Repository Pattern on MSDN.

Each API endpoint has the following service contracts:
  • Discover object identifiers
  • Find the object with the given identifier
  • Find all objects
  • Find all objects that match a set of identifiers
  • Find all objects through pagination
These service contracts are reflected in the code by the following three interfaces:
  • IRepository<TKey, TValue>
    • Find(identifier)
    • FindAll()
    • FindAll(identifiers)
    • extends IDiscoverable<TKey>
    • extends IPaginator<TValue>
  • IDiscoverable<TKey>
    • Discover()
  • IPaginator<TValue>
    • FindPage(page)
    • FindPage(page, pageSize)
Additionally, endpoints can have endpoint-specific service contracts. These are implemented on endpoint-specific repository interfaces.

For example: the recipes service has service contracts that allow you to search for recipes by input/output items. These are implemented as follows.
  • IRecipeRepository
    • DiscoverByInput(identifier)
    • DiscoverByOutput(identifier)
    • extends IRepository<int, Recipe>

Quickstart: Quaggans

Find By ID

TKey : string
TValue : Quaggan

Step 1
Create an instance of the IRepository.

IRepository<string, Quaggan> service;
service = GW2.V2.Quaggans;

Step 2
Discover object identifiers.
Underlying service contract: https://api.guildwars2.com/v2/quaggans

ICollection<string> keys = service.Discover();

Step 3
Find the object with the given identifier.
Underlying service contract: https://api.guildwars2.com/v2/quaggans/{key}

foreach (string key in keys)
{
    Quaggan quaggan = service.Find(key);
}

Completed example

var service = GW2.V2.Quaggans;
foreach (string key in service.Discover())
{
    var quaggan = service.Find(key);
}

Find All

TKey : string
TValue : Quaggan

Step 1
Create an instance of the IRepository.

IRepository<string, Quaggan> service;
service = GW2.V2.Quaggans;

Step 2
Find all objects.
The result is a dictionary.
Underlying service contract: https://api.guildwars2.com/v2/quaggans?ids=all

IDictionaryRange<string, Quaggan> quaggans;
quaggans = service.FindAll();

Step 3
Print the number of objects found.
The dictionary has additional properties that provide information about the number of found objects as well as the total number of objects in the repository.

string message = "Found " + quaggans.SubtotalCount + " objects\n";
message += "Total number of objects: " + quaggans.TotalCount;

> Found 35 objects
> Total number of objects: 35

Completed example

var service  = GW2.V2.Quaggans;
var quaggans = service.FindAll();
string message = "Found " + quaggans.SubtotalCount + " objects\n";
message += "Total number of objects: " + quaggans.TotalCount;
Console.WriteLine(message);

Find All By ID

TKey : string
TValue : Quaggan

Step 1
Create an instance of the IRepository.

IRepository<string, Quaggan> service;
service = GW2.V2.Quaggans;

Step 2
Discover all object identifiers.
Underlying service contract: https://api.guildwars2.com/v2/quaggans

ICollection<string> keys = service.Discover();

Step 3
Find all objects that match the set of identifiers.
The result is a dictionary.
Underlying service contract: https://api.guildwars2.com/v2/quaggans?ids=id1,id2,id3,idn

IDictionaryRange<string, Quaggan> quaggans = service.FindAll(keys);

Step 4
Print the number of objects found.
The dictionary has additional properties that provide information about the number of found objects as well as the total number of objects in the repository.

string message = "Found " + quaggans.SubtotalCount + " objects\n";
message += "Total number of objects: " + quaggans.TotalCount;

> Found 35 objects
> Total number of objects: 35

Completed example

var service = GW2.V2.Quaggans;
var keys = service.Discover();
var quaggans = service.FindAll(keys);
string message = "Found " + quaggans.SubtotalCount + " objects\n";
message += "Total number of objects: " + quaggans.TotalCount;
Console.WriteLine(message);

Find By Page

T : Quaggan

Step 1
Create an instance of the IPaginator. Remember that IRepository extends IPaginator.

IRepository<string, Quaggan> service;
service = GW2.V2.Quaggans;

Step 2
Configure the page and (optionally) page size.

int page = 0;
int pageSize = 10;

Step 3
Find a page.
The result is a collection.
Underlying service contract: https://api.guildwars2.com/v2/quaggans?page=0&page_size=10

ICollectionPage<Quaggan> quaggans = service.FindPage(page, pageSize);

Step 4
Print the number of objects found.
The collection has additional properties that provide information about the current page's index, the total number of pages, the number of items shown, the maximum number of items to show and the total number of items across all pages.

string message = "Showing page " + (quaggans.Page + 1) + "\n";
message += "Number of pages: " + quaggans.PageCount + "\n";
message += "Showing " + quaggans.SubtotalCount + " objects\n";
message += "Maximum objects per page: " + quaggans.PageSize + "\n";
message += "Total number of objects: " + quaggans.TotalCount;

> Showing page 1
> Number of pages: 4
> Showing 10 objects
> Maximum objects per page: 10
> Total number of objects: 35

Completed example

var service = GW2.V2.Quaggans;
ICollectionPage<Quaggan> quaggans = null;
do
{
    if (quaggans == null)
    {
        var page = 0;
        var pageSize = 10;
        quaggans = service.FindPage(page, pageSize);
    }
    else
    {
        quaggans = service.FindPage(quaggans.Page + 1, quaggans.PageSize);
    }

    string message = "Showing page " + (quaggans.Page + 1) + "\n";
    message += "Number of pages: " + quaggans.PageCount + "\n";
    message += "Showing " + quaggans.SubtotalCount + " objects\n";
    message += "Maximum objects per page: " + quaggans.PageSize + "\n";
    message += "Total number of objects: " + quaggans.TotalCount;

    Console.WriteLine(message);
}
while (quaggans.Page + 1 < quaggans.PageCount);

Last edited Feb 7, 2015 at 10:24 AM by StevenLiekens, version 18