API:2

From Guild Wars 2 Wiki
Jump to: navigation, search

Version 2 of the Guild Wars 2 API was first mentioned on July 16th 2014, when the root and quaggans endpoint was made available. On September 8th 2014, the commerce endpoints were enabled, and on February 24th, 2015 the account endpoints were enabled.

This version is primarily an interface change, introducing a resourceful structure to access elements and the ability to query multiple resources at once. Version 2 is publicly available over HTTPS, though several endpoints that access account information require authentication via an API key.

Active endpoints

The base URL for all endpoints is https://api.guildwars2.com.

Accessing resources

Each endpoint can be accessed directly to get a list of resources. Each resource can be accessed as a subpath of the endpoint. Alternatively, a single resource can also be accessed by specifying the id query parameter at the base endpoint. Multiple resources can be specified by specifying the ids query parameter instead. The latter expects a comma-separated list of identifiers and returns an array of objects instead.

For example, /v2/quaggans returns a list of quaggan identifiers, e.g. "hat" and "box".

  • A single resource, e.g. the "hat" quaggan, can be accessed at /v2/quaggans/hat or /v2/quaggans?id=hat.
  • Multiple resources, e.g. both the "hat" and "box" quaggans, can be accessed at /v2/quaggans?ids=hat,box.

Some resources accept ids=all to expand all resources at once.

Paging

The endpoints support paging using the page and page_size query parameters. Specifying a page will automatically expand alls resources. The default page size is 50, the maximum size is currently 200.

When accessing a page, additional HTTP response headers may be available:

  • X-Page-Size – The size of a page (like the page_size query parameter).
  • X-Page-Total – The total number of pages.
  • X-Result-Count – The number of resources on the current page (lower or equal to the page size).
  • X-Result-Total – The total number of resources.

Authentication

All of the endpoints which fetch account data require the use of an API key. There are currently two ways to provide an API key along with your request.

  • Adding the Authorization HTTP header to your request with the value Bearer <API key>.
  • Adding the parameter ?access_token=<API key> to your request URL.

Localisation

All of the endpoints which are locale-aware accept a language parameter. There are currently two ways to provide this language parameter along with your request.

  • Adding the Accept-Language HTTP header with the value of <language>, which also gets set by the browser by default.
  • Adding the parameter ?lang=<language> to your request URL.

Valid languages are en, es, de, fr, ko and zh. If no language parameter is set, the language defaults to en.

Errors

Standard HTTP status codes are used to express errors when using the API. In addition, a JSON response will be returned that gives additional information about the reason (if applicable).

Requesting a non-existant endpoint will yield a HTTP status code 404 with an HTML output.

Requesting an authenticated endpoint without specifying an API Key, or specifying an invalid key, will yield an HTTP 403 error with a JSON output.