API Specifications

This page is a description of the cover story and the necessary details. Specifications for each of the components are clear about what is defined and what is not defined. Furthermore, specifications indicate what areas are likely to change in the future. A specification is a difficult document to write, and it is more than just a paragraph or two about the component.

API Specifications

This API is build upon the RESTful service, full specifications can be found here: http://blizzard.github.com/api-wow-docs/. In its complete version, the Blizzard Community Platform API will make use of the entire service provided by Blizzard.

The base WoW component supports EU, US, KR, CN and TW regions. The list of supported regions with miscellaneous information can be retrieved by the wow_api_info() function. The component is a sort of infrastructure for other components, declaring a wow_http_request() function that take care of service communication.

wow_http_request()

This function can return two kinds of HttpResponse, either HttpResult, or HttpStatus. Often the function in the components that make use of wow_http_request throws an exception when returning a status code. Sometimes, when getting a 304 Not Modified error, for instance, the controller does not throw an exception, but handles it internally. The implementation of HttpResult and HttpStatus can be found directly in the classes. In the Drupal 8 version, the API will probably extends the HttpFoundation classes such as Symfony\Component\HttpFoundation\Response depending on how Drupal make use of it.

This function adds the following headers:

Date: the date used to sign the request. The timezone is always UTC.
Authorization (optional): the authorization header for application authentication with the remote service.

This function support:

The use of a locale, you must provide an api complaint locale if you want to make use of it. See wow_api_locale().
The use of If-Modified-Since header. Client functions should set the header explicitly before calling this function.
The use of a region. Each call should explicitly set the region to request.

WoW\RemoteEntityController

The RemoteEntityController is a base controller extending the drupal EntityController, adding required special handling for remote entity objects. This controller is designed to take care of If-Modified-Since header over the 'lastFetched' property of Guilds and Characters entities.

This controller adds a timestamp checking when loading an entity from the local database. If the entity refresh mode is WOW_REFRESH_LOAD, it compares the 'lastFetched' field of the entity to the refresh threshold defined, and trigger a refresh from the battle.net API if needed. Although this behavior introduce delay, this ensure you displays the most up-to-date information to your users. You can disable it by setting another refresh mode.

The API of this controller support basic CRUD operations (load, save, delete, view), as inherited from drupal EntityController, plus a special method 'fetch' that will call the battle.net API to retrieve the remote entity. By default, the fetch function returns a HttpResponse object, and an HttpException can be thrown, depending on the HTTP status code:

200 will merge the result with the entity and call a generic method processResult. Specialized controller can take over this behavior by implementing their own business logic (see GuildController and CharacterController for instance).
304 will do nothing on the entity, and return it as-it.
404 will break the code execution flow by throwing an HttpException and the entity will be deleted.
500 will break the code execution flow by throwing an HttpException which will be logged in the watchdog as well.

Data Services

WoW Services works in conjunction with a language, though it is different because you can choose not to install the default 'en_US' service. Drupal does not allow you to uninstall the default 'en' language, however for services this is different; loading all en_US data in your database will use extra space and is not necessary needed.

WoW Services are bound to a particular language, technically speaking the primary key is actually {wow_services}.language which is the foreign key of the languages table: {languages}.language. A service is not necessary enabled if a language is enabled, but is disabled if a language is disabled. Thus, a service cannot exist if a language is not installed.

The service is a sort of daemon, which performs some data mining periodically to ensure your configuration is up-to-date. Services operates only on Data Resources, providing information that can compliment profile information to provide structure, definition and context.

Each dataset has its own implementation, the wow base component provides an extensible service platform that can be extended by subsystems (wow_data_character_classes, and wow_data_character_races are managed by the WoW Character component for instance). Services controls the refresh rate of these data and updates the corresponding localized version in the database.

Support promise

The API is strongly based on Drupal core implementation, you can expect the API to be stable from release to release. Each major version changes will be backward compatible with the entire branch. For instance all 1.x releases will not contains API changes or will only contain backward-compatible API changes, whereas 2.x releases will not be backward-compatible with 1.x releases.

The 2.x version uses the entity system which is part of Drupal8, all entity related API will not change that much or will be proportional to the gap between Drupal7 and Drupal8. Also, test suit and classes follows the PSR-0 convention (note that Drupal 8 has moved to PSR-4, but there's an open issue to review this.) The wow_http_request returns a WoWResponse object, which is very similar to the Response object from the Symfony 2 component: HttpKernel. The 2.x version is a step before Drupal8, introducing refactoring, to ensure stability of the API in its 8.x version.

There is no scheduled release train, all minor version such as 2.1, 2.2, may or may not contain new feature, bug fixes and backward-compatible API changes. The battle.net service evolves continuously, sometimes adding a new locale, or new resources. Because functionality like wow_api_info() are static, reflecting a change that concern a static implementation into the module should result in a new release. Each changes will be announced in the changelog and only pushed in the current branch; older branches will not be supported once a major release will be tagged as stable.