The eRepublik API

From eRepublik Official Wiki
Revision as of 00:05, 9 August 2011 by Sampo555 (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
Languages: 
EnglishIcon-English.png


Speech balloon.png Menu

Erepublik api.png


The eRepublik API (Application Programming Interface) is an interface that players can use to create various programs and tools using information from the game or to perform limited actions in the game. The eAPI delivers data in application-friendly formats like XML and JSON and also offers functions to interact with the game's ecosystem.

History

The eAPI exists since January 2009 and has been changed and extended a lot since then. Its continuous improvement was put on hold in the middle of 2009. In 2010, the eAPI was completely updated to reflect the changes of a major update to the eRepublik's economy. The eAPI has become an important part of eRepublik and is used in an increasing number of extraordinary applications, developed by the active eRepublik community.

Version 0.6 – 2010-05-15
Documentation of the new eAPI which reflects all changes of eRepublik V2.
Version 0.5 – 2009-01-22
Last documentation about the former eAPI which was used until the release of eRepublik V2.

Uses

The eAPI is a language and platform agnostic set of http services that can be used to build third party applications around eRepublik. The current eAPI can be separated into 2 major categories:

You can retrieve information about citizens, companies, wars and similar entities on eRepublik. The data will be returned in either XML or JSON data formats. These functions are available to the public and may be used without any authorization or registration.

eRepublik users can authenticate themselves to your application using their eRepublik citizen account credentials without having to hand out these credentials. You can therefore build secure applications which require its users to authenticate them as eRepublik citizens.

There's no more banning for going over the limit any more and the way the request limit works now is that you can do a maximum of 20 requests in 4 seconds (18000 requests per hour if you obey the limit). If you do 21 requests in under 4 seconds, that last request will time out -- super easy to handle in any mainstream language. But after the 4 seconds are up you can do 20 more.

Feeds are cached following this list :

  • every 10 minutes : citizen by id, companies, market offers, battles, combatants
  • every 2 hours  : regions, wars
  • every 6 hours  : citizens by region
  • every 20 hours  : countries, industries

OAuth

For functions where security plays an important role, like the user authentication process, the eAPI uses a mechanism called OAuth in version 1.0a. OAuth is a renowned standard for secure authentication which is used by many sites on the Internet. If you are familiar with OpenID, you pretty much already know how to use OAuth.

You can find more information and example of how to use the OAuth here : The OAuth. There are ready-to-use modules and libraries for OAuth for most programming languages out there, so instead of telling you how to implement OAuth yourself, we'd like to point you to http://oauth.net/code/ for a list of these modules and encourage you to use them. For more (or “all”) information on OAuth, visit the official webpage at http://oauth.net/.

Getting Help

If you have any problems or questions regarding the eAPI, here are some places you can find help: