Play Now Login Create Account
illyriad
  New Posts New Posts RSS Feed - Combat API Keys
  FAQ FAQ  Forum Search   Register Register  Login Login

Combat API Keys

 Post Reply Post Reply Page  12>
Author
GM Stormcrow View Drop Down
Moderator Group
Moderator Group
Avatar
GM

Joined: 23 Feb 2010
Location: Illyria
Status: Offline
Points: 3926
Post Options Post Options   Thanks (0) Thanks(0)   Quote GM Stormcrow Quote  Post ReplyReply Direct Link To This Post Topic: Combat API Keys
    Posted: 13 Aug 2010 at 17:07
INTRODUCTION TO THE COMBAT API KEY
We now have a combat report API key in place, ready for testing.

[NOTE: Updated details here: http://forum.illyriad.co.uk/14oct14-prestige-scrolls_topic5897.html]

This is a key that an individual player can generate, and revoke (or rather, generate a new key) from their Account Details page on a soon-to-be-released submenu on this page, called "API Keys".

It differs from the combat report XML in that it is a generic key which essentially says "I hereby grant the holder of this key the right to access all my combat event logs in XML format until such time as I revoke the key by changing it".

A player who issues a Combat API Key can then use this unique, individual key to query a page that will produce a list of combat events that can then be queried via the individual report identifier, and they can share this key with anyone they choose.

Players can pass their Combat API key to third parties (such as alliance techies, or killboard website operators) and these third parties can then query this page on behalf of the player, and retrieve the individual combat reports for every combat this player has been involved in.


ISSUING & REVOKING YOUR COMBAT API KEY
This will be performed on a soon-to-be-publically-released submenu on the account details page, called "API Keys".

For the moment, whilst we're in testing, all players can get their (revoke/issue new) Public Combat API Key here:


You will have a list of keys here - or, on your first visit, the option to issue a Combat API Key for the first time. 

To create a Combat Reports API Key, press the "Issue API Key" button under the Combat Reports API Key heading, and you will have a key immediately granted to you.

If you already have a key, you will have the option to "Change API Key" which will instantly disable your old key, and generate a new one for you.

Only the Account owner will be able to issue or revoke keys - this function will not be available to Account Sitters.

USING THE API KEY TO GET AN XML LIST OF AVAILABLE COMBAT REPORTS


The API Key is in the format:
[Server Name]-[KeyType]-[Key]
This helps people identify which server to query and what page to query with the key.

A sample full combat API key for UK1 might look like this:
UK1-COMRP-AQAAABoolkA8l0qQ7kL5Vpxmk-LwCjrv0qh5f9uB6M10saMBnAi01_0IiV4a-pnxWDUF5UcAhtw1SNQ2n0XGbgvb6gw=
This identifies this key as being good for pulling data from Server [UK1] for Combat Reports [COMRP], and the remainder of the key is an encrypted piece of data that identifies the player to us (twinned with the rights he has given to this key).
Other keys for (eg) Diplomatic Reports will be generated in due course.

To query a key for the first time, call the following page:
http://uk1.illyriad.co.uk/view_combat_reports_api.asp?APIKey=[insert player's full Combat API Key including the server and keytype here]

and so, using the example above, your query would be:

http://uk1.illyriad.co.uk/view_combat_reports_api.asp?APIKey=UK1-COMRP-AQAAABoolkA8l0qQ7kL5Vpxmk-LwCjrv0qh5f9uB6M10saMBnAi01_0IiV4a-pnxWDUF5UcAhtw1SNQ2n0XGbgvb6gw=

WHAT DOES THE PAGE RETURN?

Sample (will not work in reality)

<combateventsapi>
<server>
<name>UK1</name>
<servercountrycode>gb</servercountrycode>
<serverlanguagecode>en</serverlanguagecode>
<serverlivedate>2010-02-21T21:53:01.190</serverlivedate>
<datagenerationdatetime>2010-08-13T16:30:43.040</datagenerationdatetime>
</server>

<player id="1"/>
<playerapikey id="
UK1-COMRP-AQAAABoolkA8l0qQ7kL5Vpxmk-LwCjrv0qh5f9uB6M10saMBnAi01_
0IiV4a-pnxWDUF5UcAhtw1SNQ2n0XGbgvb6gw="/>


<combatevents>
<uniquecombatidentifier>
<server id="UK1"/>
<combatguid id="F94B7AC1-CFB8-4DE8-A211-044D1A4DAC18"/>
<troopmovementevent id="507040"/>
<datacomplete id="1"/>
<personalcombatkey id="AQAAACTYblel0LzEsSb7kiZcZg0hQJZCDmbi_sgo82Ej6iKr"/>
<combatoccurrencedate>2010-08-06T03:09:10.523</combatoccurrencedate>
</uniquecombatidentifier>

<uniquecombatidentifier>
<server id="UK1"/>
<combatguid id="4D389937-545A-4CC0-A7E8-4EA27487DAAE"/>
<troopmovementevent id="509341"/>
<datacomplete id="1"/>
<personalcombatkey id="AQAAAFICvEs1DXLWCN2fesfs61oCyonjDBukVnB0TxJJg2t3"/>
<combatoccurrencedate>2010-08-06T16:39:30.907</combatoccurrencedate>
</uniquecombatidentifier>
</combatevents>


Breaking it down, you have:
  • The standard Server Identification snippet, followed by
  • The PlayerID who this Key belongs to, and the exact key you just used
  • A list of combat events that this player has been involved in, along with the <personalcombatkey> identifier so you can then go off and query the specific event for the full details, using the standard:
    http://uk1.illyriad.co.uk/view_combat_report.asp?FCEI=[insert <personalcombatkey> here]

HOW TO CHOOSE WHAT EVENTS YOU NEED TO QUERY


1. You may already have the report from another player
Within:

<uniquecombatidentifier>
<server id="UK1"/>
<combatguid id="4D389937-545A-4CC0-A7E8-4EA27487DAAE"/>
<troopmovementevent id="509341"/>
<datacomplete id="1"/>
<personalcombatkey id="AQAAAFICvEs1DXLWCN2fesfs61oCyonjDBukVnB0TxJJg2t3"/
<combatoccurrencedate>2010-08-06T16:39:30.907</combatoccurrencedate>
</uniquecombatidentifier>


IF
  • You already have a combat report with this <server id> and
  • You already have a combat report with this <combatguid id> and
  • You already have a combat report with this <troopmovementevent id>
THEN
IF
  • This new report has a less than or equal to ( <= ) <datacomplete id> than the one you currently have:
WHEN TRUE (YES, YOU HAVE THIS "NEW" REPORT ALREADY AND THE VERSION YOU HAVE IS AS GOOD AS, OR BETTER THAN, THE NEW REPORT) THEN
  • Don't query this report - you already have everything you need
WHEN FALSE (NO, THIS "NEW" REPORT HAS MORE ACCURATE DATA THAN THE REPORT YOU CURRENTLY HAVE) THEN
  • Query this report using the <personalcombatkey id> and replace your existing report with this one
ELSE
  • This is a new report and you should import it


2. You don't need to query the complete player history every time, to decide what's new

Obviously we don't want you to be querying a complete player history every time you pull the API key.

So there is an additional parameter we'd like you to use when you subsequently query view_combat_reports_api.asp - this parameter is called LastDateTime

This should be set to the most recent <combatoccurrencedate> for the <player ID> whose key you are using.

If you don't have any data for this player so far, then please do not provide the parameter.

Because there is a small chance that you might have two combat events from the same player occurring at the same millisecond, we will return the event you already have at that datetime stamp, so please be prepared to ignore the first event returned - as you may already have it (see above for how to decide).

The LastDateTime parameter is in the same format it was provided in originally in the <combatoccurrencedate> field of the last report you have from this player, such as: 2010-08-06T03:09:10.513

So, a first API Key query might look like this:
http://uk1.illyriad.co.uk/view_combat_reports_api.asp?APIKey=UK1-COMRP-AQAAABoolkA8l0qQ7kL5Vpxmk-LwCjrv0qh5f9uB6M10saMBnAi01_0IiV4a-pnxWDUF5UcAhtw1SNQ2n0XGbgvb6gw=
and a subsequent one might look like this:
http://uk1.illyriad.co.uk/view_combat_reports_api.asp?APIKey=UK1-COMRP-AQAAABoolkA8l0qQ7kL5Vpxmk-LwCjrv0qh5f9uB6M10saMBnAi01_0IiV4a-pnxWDUF5UcAhtw1SNQ2n0XGbgvb6gw=&LastDateTime=2010-08-06T03:09:10.513
which will only return those combat events related to the player since (and including) the event on the LastDateTime timestamp.


HOW OFTEN CAN I QUERY A PLAYER'S API KEY?

For the purposes of development, we haven't set a limit.

However, we will impose a limit of once per hour for a particular key query (from the same querying source) at some point in the future.





Edited by GM ThunderCat - 10 Dec 2014 at 06:20
GM Stormcrow | Twitter | Facebook | G+
Back to Top
GM Stormcrow View Drop Down
Moderator Group
Moderator Group
Avatar
GM

Joined: 23 Feb 2010
Location: Illyria
Status: Offline
Points: 3926
Post Options Post Options   Thanks (0) Thanks(0)   Quote GM Stormcrow Quote  Post ReplyReply Direct Link To This Post Posted: 13 Aug 2010 at 22:15
Please feel free to give any and all feedback on this.

It's "live testing" at the moment, but we intend to release it publically mid-next week, if there are no obvious bugs reported.

Best,

SC
Back to Top
Larry View Drop Down
Wordsmith
Wordsmith


Joined: 10 Mar 2010
Status: Offline
Points: 114
Post Options Post Options   Thanks (0) Thanks(0)   Quote Larry Quote  Post ReplyReply Direct Link To This Post Posted: 13 Aug 2010 at 22:37
Initial reaction: WOOT!

*goes and reads details*

EDIT: Awesome.

Things that make me happy:
1) ITS AN API KEY YES!
2) As is, its awesome for killboards.

Things that would be cool in the future:
1) JSON (I know I sound like a broken record, but its gorgeous)
2) As is, it is NOT really setup for real time troop monitoring.
3) somewhat of a different thing I suppose, but I'm a big fan of RESTful services.

How to fix:
1) self explanatory really

2) Make a "troops sent" type event that catalogs what army (and its composition) was sent when, to what destination.  This way, particularly for players with multiple cities / accounts all with troops / diplos on the move, I could build a page that would let a player know the status of ALL their troops simultaneously, and that would be epic. I'm not proposing that the server be responsible for the current status of all troops. If the API key holder simply knows at what time the troops left, at what speed, and to what destination, they are perfectly capable of looking at a clock themselves and figuring out how far along the route the unit is.

3) will vary wildly depending on your backend


Edited by Larry - 13 Aug 2010 at 22:48
Back to Top
fluffy View Drop Down
Forum Warrior
Forum Warrior
Avatar

Joined: 02 Mar 2010
Status: Offline
Points: 335
Post Options Post Options   Thanks (0) Thanks(0)   Quote fluffy Quote  Post ReplyReply Direct Link To This Post Posted: 14 Aug 2010 at 05:25
boo, how about an api key thats useful, like for market transactions or something.  /me whistles.  I have plans that I can't complete!
Back to Top
GM Stormcrow View Drop Down
Moderator Group
Moderator Group
Avatar
GM

Joined: 23 Feb 2010
Location: Illyria
Status: Offline
Points: 3926
Post Options Post Options   Thanks (0) Thanks(0)   Quote GM Stormcrow Quote  Post ReplyReply Direct Link To This Post Posted: 14 Aug 2010 at 12:43
Originally posted by fluffy fluffy wrote:

boo, how about an api key thats useful, like for market transactions or something.  /me whistles.  I have plans that I can't complete!


Will be coming with Trade v2.

Trade is changing, entirely, completely, utterly and totally - so we're not going to develop anything against the current trade system.
Back to Top
fluffy View Drop Down
Forum Warrior
Forum Warrior
Avatar

Joined: 02 Mar 2010
Status: Offline
Points: 335
Post Options Post Options   Thanks (0) Thanks(0)   Quote fluffy Quote  Post ReplyReply Direct Link To This Post Posted: 15 Aug 2010 at 03:32
you guys keep saying that stuff is changing, but I DONT SEE ANYTHING! (besides sov, but that just takes too much effort :P and the town layout...but now i dont know where anything is bah lol)  I look forward to the new trade system, something finally worthwhile tehee
Back to Top
Tamaeon View Drop Down
Wordsmith
Wordsmith
Avatar

Joined: 19 Dec 2011
Location: Centrum
Status: Offline
Points: 152
Post Options Post Options   Thanks (0) Thanks(0)   Quote Tamaeon Quote  Post ReplyReply Direct Link To This Post Posted: 09 Feb 2013 at 20:43
Do the API keys still exist? I can't find anything under account details. Cry
Back to Top
GM ThunderCat View Drop Down
Moderator Group
Moderator Group
Avatar
GM

Joined: 11 Dec 2009
Location: Everywhere
Status: Offline
Points: 2183
Post Options Post Options   Thanks (0) Thanks(0)   Quote GM ThunderCat Quote  Post ReplyReply Direct Link To This Post Posted: 10 Dec 2014 at 06:16
We have added the occurrence_datetime to the combat report, should be millisecond timing:

<uniquecombatidentifier>
<server id="elgea"/>
<combatguid id="..."/>
<troopmovementevent id="..." occurrence_datetime="2014-12-09T20:02:57.703"/>
<datacomplete id="1"/>
</uniquecombatidentifier>


Edited by GM ThunderCat - 10 Dec 2014 at 06:16
Back to Top
Tamaeon View Drop Down
Wordsmith
Wordsmith
Avatar

Joined: 19 Dec 2011
Location: Centrum
Status: Offline
Points: 152
Post Options Post Options   Thanks (0) Thanks(0)   Quote Tamaeon Quote  Post ReplyReply Direct Link To This Post Posted: 02 Jan 2015 at 15:27
For some reason I'm no longer able to access my personal API key.

<errormsg>This API Key does not exist, or has been revoked by the owning player.</errormsg>

All I'm getting is the error message above. I'd simply generate a new key, but wouldn't like to lose the reports which are currently stored.

I'm trying to call it using my api key affixed with "?since=2014-12-01T00:00:01".

Can someone confirm if the API is still up, or correct me if I'm doing something wrong?

Cheers


"How happy is the blameless vestal's lot! The world forgetting, by the world forgot. Eternal sunshine of the spotless mind! Each prayer accepted, and each wish resigned."
Back to Top
GM Stormcrow View Drop Down
Moderator Group
Moderator Group
Avatar
GM

Joined: 23 Feb 2010
Location: Illyria
Status: Offline
Points: 3926
Post Options Post Options   Thanks (0) Thanks(0)   Quote GM Stormcrow Quote  Post ReplyReply Direct Link To This Post Posted: 02 Jan 2015 at 17:03
Originally posted by Tamaeon Tamaeon wrote:

For some reason I'm no longer able to access my personal API key.

<errormsg>This API Key does not exist, or has been revoked by the owning player.</errormsg>

All I'm getting is the error message above. I'd simply generate a new key, but wouldn't like to lose the reports which are currently stored.

I'm trying to call it using my api key affixed with "?since=2014-12-01T00:00:01".

Can someone confirm if the API is still up, or correct me if I'm doing something wrong?

Cheers


Hi Tamaeon,

We're running into some timeout issues with queries on the API key, which are producing a "Does not exist" error message.  So it's not anything you're doing.  We're looking into it and will let you know when we resolve.

FYI, revoking / issuing a new key doesn't remove access to any historic reports - your new key will have full access to all the data since your first ever key was generated; it's just that the old key ceases to retrieve any data (historic or new).

Best,

SC
Back to Top
 Post Reply Post Reply Page  12>
  Share Topic   

Forum Jump Forum Permissions View Drop Down

Forum Software by Web Wiz Forums® version 12.03
Copyright ©2001-2019 Web Wiz Ltd.