API:Best practices
This pages serves as a list of best practices when it comes to working with the API, as it has many inconsistencies that accumulated over the years or simply general guidelines of how to work with it.
Making requests
The default response from virtually every endpoint is to return a list of valid IDs for that endpoint.
If requiring more than one ID, rather than making a request for each ID (e.g. https://api.guildwars2.com/v2/traits/1 and https://api.guildwars2.com/v2/traits/2 , or https://api.guildwars2.com/v2/traits?ids=1 and https://api.guildwars2.com/v2/traits?ids=2), it is often better to combine multiple ID requests using a comma (e.g. https://api.guildwars2.com/v2/traits?ids=1,2,3,4,5). Up to 200 individual IDs can be requested in one request. Pagination is also possible. Refer to API:2#Accessing resources for further information.
Common problems
Rate Limit
Max Burst Size (bucket size): 300
Refill Rate: 5 tokens per second (300 per minute)
With 300 burst and a refill of 5 tokens per second, you will get a reliable stream of requests with no 429s.
Invalid API-Keys
Sometimes API-Keys that are otherwise perfectly fine will return "Invalid key" randomly, when retrying the same key it often times works perfectly fine afterwards. It is recommended to keep retrying the key at a later time or in intervals instead of just marking it as invalid.
Schema Changes
When using an ISO Datetime to force a particular schema version, it is important to bear in mind that changing enum values is not considered a breaking change. Depending on your chosen language and modelling this could lead to errors if your application cannot handle unexpected values in enums. Thus it is important to make sure you handle unexpected values for enums.
For instance, in API:2/continents the region field inside the mastery_points entries was updated to add the value Jade as an enum option without an API schema change.
External resources
- GW2 Development Community Discord
- API Status page by GW2Efficiency
- (Link to GW2Efficiency mock API key)
