23FEB15: API / XML NOTIFICATIONS |
Post Reply |
Author | |||||
GM Stormcrow
Moderator Group GM Joined: 23 Feb 2010 Location: Illyria Status: Offline Points: 3926 |
Post Options
Thanks(0)
Posted: 23 Feb 2015 at 20:56 |
||||
API KEY AND XML FEED FOR ACCOUNT & TOWN NOTIFICATIONS
For those of you who are building new third-party tools, you might be glad to know that there is now an API Key XML feed in place for account & town Notifications. For those of you who don't know what an API Key is, it's essentially a way you can share specific data from your account (in this case your player accounts' ingame Notifications) with a trusted third party - but without giving them sitting rights to your account. You might, for example, want to share this key with your alliance leadership, so they can keep an eye on what's happening to your cities. Someone might want to write an app that sends you an out-of-game email or a push notification to your mobile phone when your building queue is empty, when your harvesters get home or when an army arrives at its destination. There are lots of possibilities; and by giving you the tools to write what you want, we all benefit the most.
To be a bit more specific, by sharing your Notifications API Key you are saying "I don't mind you (and anyone you share my key with) from reading my account's ingame Notifications without any further permissions from me, but that's all, and I reserve the right to revoke this key at any time, which will prevent everyone who has that revoked key from accessing any new Notifications information relating to my Player account from the moment I revoke the key." The API key is something that an individual player can generate, and revoke (or more specifically, generate a new key which instantly revokes the previous key) from their Account & Preferences page in the "API Keys" submenu. ISSUING & REVOKING YOUR NOTIFICATIONS API KEY
Account sitters can generate and/or revoke API keys. USING THE API KEY TO GET AN XML LIST OF AVAILABLE NOTIFICATIONS - A PROGRAMMERS' GUIDE If you're not a programmer, then the following is probably not relevant, and you can happily ignore or skip the rest of this post! The API Key is in the format: <ServerName>-<KeyType>-<Key> This helps you identify which server to query (we currently only have elgea) and what page to query with the key. A sample full Notification API key might look like this (please note that this key is not valid and will return no data):
This identifies this key as being good for pulling data from ServerName "elgea" (which includes Broken Lands) for Notifications "NOTIF", 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). To query a key for the first time, call the following page (please note that this page will not work, as the key is invalid) with the key attached after the last forward slash:
and so, using the example above, your query would be (please note that this link will not work as the key is invalid):
WHAT DOES THE PAGE RETURN? Sample:
(You may need to scroll the page to the right, from the bottom of the post, to see the full <notificationdetail> text) Each individual <notification> in the <notifications> group is ordered ascending numerically by <notification id>, so your most recent notifications are at the bottom of the list.
HOW TO MAKE SUBSEQUENT QUERIES You don't need to query the complete player's notification history every time! Obviously we don't want you to be querying a complete player history every time you pull the Notifications API, and you probably don't want to be parsing it only to discard, either. So there is an additional parameter we'd like you to pass when you subsequently query the Notifications API - this integer parameter is called <LastNotificationID>, and should be added after the Key, separated by a "?". <LastNotificationID> is based on a linear numbering of Notifications issued, so it will be an historic record. For each player, you only need to query events from the last notification you received for that player, therefore, this should be set to the most recent <notification id> for the <player id> whose key you are using. So if you've retrieved a specific players' Notifications, and now want to see all new Notifications for that player's API Key since their last Notification (in the example above <notification id> 645592820) then you query:
... which will only return those new Notifications related to the player since (and including) the last Notification with the supplied <LastNotificationID>. So you should have one duplicate Notification (the first <notification>) with each query, with the <notification id> you had last (the <LastNotificationID> parameter). HOW OFTEN CAN I QUERY A PLAYER'S API KEY? For the purposes of development, we haven't yet set a limit. However, we will probably impose a limit for a particular key query (from the same querying source) at some point in the future, simply to preserve server resources and bandwidth. It all rather depends on how you player-programmers choose to use the API key system! WHAT DATA IS AVAILABLE It's everything in the current player's Notification list for all towns. This list is archived quite regularly, as notifications pile up reasonably quickly, depending on activity. We are not providing access to the archive at present, however, if you supply a <LastNotificationID> and do not receive the (duplicate) data for that specific NotificationID, then you know you're missing notifications in that player's history - most likely because they've been archived. This will depend on a balance of how regularly you query the Notifications API, and how regularly we archive Notifications. Hopefully we (you and us both) can collectively strike a balance between two potentially competing requirements. For the sake of information, our Notifications archiving policy is a batch task that runs hourly and archives any notification that is more than 14 days (336 hours) old. Please do keep us appraised of whether you do not receive the duplicate data for a specifically supplied <LastNotificationID> , along with details of your last query and the previous one, and we can see about either preserving notifications for longer before archiving, or about allowing access to the archives. Enjoy! SC EDIT (SC): Added the missing Notifications archiving policy information EDIT2 (SC): Clarified sort order of notifications is ascending numeric Edited by GM Stormcrow - 23 Feb 2015 at 21:53 |
|||||
Tensmoor
Postmaster General Joined: 07 Apr 2015 Location: Scotland Status: Offline Points: 1830 |
Post Options
Thanks(0)
|
||||
I've just noticed that not all notifications are included in the download from the api. In particular anything under the 'Friends' heading seems to be missing. I sent a friend request from my alt to my main and got a notification in-game but an hour later there is no sign of it in the download. Not of great significance and not anything to panic about but it does make me wonder if there are others missing. Tens
|
|||||
Dungshoveleux
Postmaster Joined: 09 Nov 2013 Status: Offline Points: 958 |
Post Options
Thanks(0)
|
||||
This means Tensmoor can now automate the creation of a database of rare mineral and rare herb location by feeding off the notifications of several players.
|
|||||
Tensmoor
Postmaster General Joined: 07 Apr 2015 Location: Scotland Status: Offline Points: 1830 |
Post Options
Thanks(0)
|
||||
Couple of problems with that:
As far as I'm concerned when a player shares any of their api keys with somebody else there should be a clear understanding of what that data will be used for. An example would be if somebody is being attacked then the monitoring of diplo/military activity would probably be agreed on but not trade/research events. Sharing of keys is something that folks need to be careful with - in the wrong hands it can cause problems. |
|||||
Jejune
Postmaster General Joined: 10 Feb 2013 Status: Offline Points: 1035 |
Post Options
Thanks(0)
|
||||
Hello, Illyriad tech immortals.
Quick (and maybe naive) question: is there any master list of all the notification types and their respective IDs? Thanks!
|
|||||
Tensmoor
Postmaster General Joined: 07 Apr 2015 Location: Scotland Status: Offline Points: 1830 |
Post Options
Thanks(0)
|
||||
No. When they announced the api they said that they would not be publishing a list of the ids/types etc as it was very subject to change.
|
|||||
Post Reply | |
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 |