Combat API Keys |
Post Reply | Page 12> |
Author | ||
GM Stormcrow
Moderator Group GM Joined: 23 Feb 2010 Location: Illyria Status: Offline Points: 3926 |
Post Options
Thanks(0)
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] WHAT DOES THE PAGE RETURN? Sample (will not work in reality)
Breaking it down, you have:
HOW TO CHOOSE WHAT EVENTS YOU NEED TO QUERY 1. You may already have the report from another player Within:
IF
THEN IFELSE
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.513which 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
Moderator Group GM Joined: 23 Feb 2010 Location: Illyria Status: Offline Points: 3926 |
Post Options
Thanks(0)
|
|
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 |
||
Larry
Wordsmith Joined: 10 Mar 2010 Status: Offline Points: 114 |
Post Options
Thanks(0)
|
|
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 |
||
fluffy
Forum Warrior Joined: 02 Mar 2010 Status: Offline Points: 335 |
Post Options
Thanks(0)
|
|
boo, how about an api key thats useful, like for market transactions or something. /me whistles. I have plans that I can't complete!
|
||
GM Stormcrow
Moderator Group GM Joined: 23 Feb 2010 Location: Illyria Status: Offline Points: 3926 |
Post Options
Thanks(0)
|
|
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. |
||
fluffy
Forum Warrior Joined: 02 Mar 2010 Status: Offline Points: 335 |
Post Options
Thanks(0)
|
|
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
|
||
Tamaeon
Wordsmith Joined: 19 Dec 2011 Location: Centrum Status: Offline Points: 152 |
Post Options
Thanks(0)
|
|
Do the API keys still exist? I can't find anything under account details.
|
||
GM ThunderCat
Moderator Group GM Joined: 11 Dec 2009 Location: Everywhere Status: Offline Points: 2183 |
Post Options
Thanks(0)
|
|
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 |
||
Tamaeon
Wordsmith Joined: 19 Dec 2011 Location: Centrum Status: Offline Points: 152 |
Post Options
Thanks(0)
|
|
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."
|
||
GM Stormcrow
Moderator Group GM Joined: 23 Feb 2010 Location: Illyria Status: Offline Points: 3926 |
Post Options
Thanks(0)
|
|
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
|
||
Post Reply | Page 12> |
Tweet
|
Forum Jump | Forum Permissions You cannot post new topics in this forum You cannot reply to topics in this forum You cannot delete your posts in this forum You cannot edit your posts in this forum You cannot create polls in this forum You cannot vote in polls in this forum |