API:2

From Guild Wars 2 Wiki
Jump to navigationJump to 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. Pages are zero indexed (the first page is page 0, second page is page 1 etc).

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.

See API key for a list of the authenticated endpoints and their required permissions.

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 and zh. If no language parameter is set, the language defaults to en.

Schemas

To allow the API the flexibility to evolve their response schemas without breaking existing applications, the API supports the notion of schema versions on endpoints that have changed. The API will translate the response data backward from the latest version down to the requested version.

Schema versions are strings that happen to be ISO 8601 datetimes in UTC (so that string comparisons provide chronological ordering), or the value latest which will always return the latest schema from the API. Production applications should always provide a known schema version to avoid breaking in the future. If no schema version is supplied, the APIs will default to the earliest version so as to maintain backward compatibility with applications that predate the introduction of schema versions.

There are currently two ways to specify a Schema version alongside a request:

  • Adding the query parameter v=<schema> to a request URL (recommended).
    • e.g., ?v=2019-02-21T00:00:00Z, ?v=latest
  • Adding the X-Schema-Version HTTP header to a request with the schema as value.

Schema versions supported by an endpoint, where applicable, are indicated on a specific endpoints Page.

The latest v2.json endpoint returns a list of known schema versions.

Responses

API requests will return a JSON response body describing the requested content, or error message, if applicable. Additionally, the HTTP response code can be used to determine the state of the response body.

Success

  • HTTP 200 will be returned if all of the requested data has been returned.
  • HTTP 206 will be returned when using the ids parameter if at least one, but not all of the provided IDs are valid.

Errors

  • HTTP 403 will be returned if attempting to access an authenticated endpoint without a valid API key, or with a valid API key without the necessary permissions.
  • HTTP 404 will be returned if an endpoint does not exist, or all of the provided IDs are invalid.
  • HTTP 502 will be returned if the server receives an invalid response from an upstream server.
  • HTTP 503 will be returned if an endpoint is disabled.
  • HTTP 504 will be returned if a gateway timeout error is received.
Retrieved from "https://wiki.guildwars2.com/index.php?title=API:2&oldid=2884030"