clash_of_clans_api is a gem to communicate with the Clash of Clans API at https://developer.clashofclans.com/.
It contains low-level methods to communicate with all existing API endpoints and aims to provide higher-level abstractions for them.
Add this line to your application’s Gemfile:
gem 'clash_of_clans_api'And then execute:
$ bundle install
Or install it yourself as:
$ gem install clash_of_clans_api
To communicate with the Clash of Clans API, an API key is required. If you like to use the library to create and manage API keys, see Token API.
The gem provides two classes for communication.
ClashOfClansApi::Api is a low-level interface that implements methods for all API endpoints.
If the request is successful, the API’s JSON response is parsed and returned, otherwise an ApiFrame::NoSuccessError is raised.
ClashOfClansApi::Client is a higher-level interface that exposes its ClashOfClansApi::Api instance through ClashOfClansApi::Client#api.
Both classes’ initializers take a single argument, the API token.
The method names for the endpoints are the same in both classes. They are derived from the API documentation by the following steps.
-
Take the path name from the documentation (e.g.
/clans/{clanTag}/currentwar/leaguegroup). -
Replace slashes (
/) with underscores (_) and keep only inner ones (clans_{clanTag}_currentwar_leaguegroup). -
In case of path arguments, singularize the path segment referenced by the argument (
clan_{clanTag}_currentwar_leaguegroup). -
Remove path argument segments (
clan_currentwar_leaguegroup). -
Remove any hyphens.
Path arguments are converted to positional arguments in the order of definition in the original path name.
Path arguments will automatically be URL-escaped.
A URL query in the form of a Hash can be passed as the named parameter query:.
Creating, listing and deleting API keys (tokens) is supported in ClashOfClansApi::TokenClient using the email address and password from the Clash of Clans Developer website.
token_client = ClashOfClansApi::TokenClient.new(email, password)
token_client.login!
# Return a list of the currently registered API keys.
token_client.list_api_keys
# Create a new API key for the IP address 127.0.0.1 and create a ClashOfClansApi::Client from it.
token = token_client.create_api_key('my_key_name', 'This is a description for my API key.', ['127.0.0.1'])
client = token.client_from_token
# Create or get an API key with the given name for the current IPv4 address.
other_token = token_client.create_or_get_api_key_for_current_ipv4_address('test_key_name', overwrite: true)
# Revoke the previously generated tokens.
token_client.revoke_api_key(token.id)
other_token.revoke
# Logging out is not required, but possible.
token_client.logoutThis feature can be useful for applications whose host changes their IP address without human interaction as well as for large (federated) applications with too many requests for a single or a few manually created tokens.
Similar to ClashOfClansApi::Api and ClashOfClansApi::Client, there is also a lower-level implementation of the token API in ClashOfClansApi::TokenApi.
However, its usage is not recommended.
Tags in Clash of Clans are subject to format restrictions.
Since those restrictions are well known, ClashOfClansApi::Tags provides class methods for checking the format (.sanitizable?) and sanitizing ill-formatted tags up to a certain degree (.sanitize).
Since the beginning of 2022, the API consistently corrects the letter O in requests to the number 0, which was not the case before.
Previously, this could lead to multiple database entries for the same player, which the .sanitize method could prevent.
While this isn’t a problem anymore in this specific use case, it might come in handy for querying user input in ones own database.