Play Now Login Create Account
illyriad
  New Posts New Posts RSS Feed - 23FEB15: API / XML NOTIFICATIONS
  FAQ FAQ  Forum Search   Register Register  Login Login

23FEB15: API / XML NOTIFICATIONS

 Post Reply Post Reply
Author
GM Stormcrow View Drop Down
Admin Group
Admin Group
Avatar
GM

Joined: 23 Feb 2010
Location: Illyria
Status: Offline
Points: 3038
Post Options Post Options   Thanks (0) Thanks(0)   Quote GM Stormcrow Quote  Post ReplyReply Direct Link To This Post Topic: 23FEB15: API / XML NOTIFICATIONS
    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
  • Go to your Account & Preferences page and click on the API submenu.

    Direct link to that page here:  http://elgea.illyriad.co.uk/#/Player/Account?page=api

  • You will have a list of keys here - or, on your first visit, the option to issue a different kinds of API Keys for the first time.

  • To create an API Key for Notifications, press the "Generate" button next to the word "Notifications".  Your Notifications API Key will appear above.

  • If you already have a key, pressing "Generate" will instantly disable your current key for this API Type, and generate a new one for you; thereby preventing continued access to your API data by anyone who knows your old key.

  • You can then choose to share the new key with anyone you trust to access your Notifications data.

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):


elgea-NOTIF-AQAAAGDX3am4eJa9JZU5yiC1aE3XGM0Rkey0dZTCB2Ksfozk7bajd5b22PsV3YbfSoKN5F-JJucBiS8k

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:

http://elgea.illyriad.co.uk/external/notificationsapi/


and so, using the example above, your query would be (please note that this link will not work as the key is invalid):

http://elgea.illyriad.co.uk/external/notificationsapi/elgea-NOTIF-AQAAAGDX3am4eJa9JZU5yiC1aE3XGM0Rkey0dZTCB2Ksfozk7bajd5b22PsV3YbfSoKN5F-JJucBiS8k


WHAT DOES THE PAGE RETURN?

Sample:


<notificationsapi>
  <server>
    <name>elgea</name>
    <servercountrycode>gb</servercountrycode>
    <serverlanguagecode>en</serverlanguagecode>
    <serverlivedate>2010-02-21T21:53:01.190</serverlivedate>
    <datagenerationdatetime>2015-02-23T01:52:41.533</datagenerationdatetime>
  </server>
  <player id="1" />
  <playerapikey id="elgea-NOTIF-AQAAAGDX3am4eJa9JZU5yiC1aE3XGM0Rkey0dZTCB2Ksfozk7bajd5b22PsV3YbfSoKN5F-JJucBiS8k" />
  <notifications>
    <notification>
      <notification id="645421399" />
      <notificationtype id="2">Building Construction Completed</notificationtype>
      <notificationoveralltype id="1">Town</notificationoveralltype>
      <notificationtown id="1" />
      <notificationdetail>[@ps=GM Stormcrow|1|DEVS|18|1|0|740-746-755-0-0-0-0-0-0-0-0-0-0|Illyriad Dev Team|Game Master|10-439-294-72] Vault L14 completed at [@t=Stormont|1|383|-1815|12735|1|1|1|51|1|GM Stormcrow|DEVS|1|15-4 wall]. Construction of Vault L15 has now begun.</notificationdetail>
      <notificationoccurrencedate>2015-02-22T18:17:19.673</notificationoccurrencedate>
    </notification>
    <notification>
      <notification id="645421403" />
      <notificationtype id="2">Building Construction Completed</notificationtype>
      <notificationoveralltype id="1">Town</notificationoveralltype>
      <notificationtown id="1" />
      <notificationdetail>[@ps=GM Stormcrow|1|DEVS|18|1|0|740-746-755-0-0-0-0-0-0-0-0-0-0|Illyriad Dev Team|Game Master|10-439-294-72] Vault L15 completed at [@t=Stormont|1|383|-1815|12737|1|1|1|51|1|GM Stormcrow|DEVS|1|15-4 wall]. Your building queue is empty.</notificationdetail>
      <notificationoccurrencedate>2015-02-22T18:17:19.720</notificationoccurrencedate>
    </notification>
    <notification>
      <notification id="645592818" />
      <notificationtype id="2">Building Construction Completed</notificationtype>
      <notificationoveralltype id="1">Town</notificationoveralltype>
      <notificationtown id="1" />
      <notificationdetail>[@ps=GM Stormcrow|1|DEVS|18|1|0|740-746-755-0-0-0-0-0-0-0-0-0-0|Illyriad Dev Team|Game Master|10-439-294-72] Arctic Warfare College L3 completed at [@t=Stormont|1|383|-1815|12739|1|1|1|51|1|GM Stormcrow|DEVS|1|15-4 wall]. Construction of Arctic Warfare College L4 has now begun.</notificationdetail>
      <notificationoccurrencedate>2015-02-23T01:52:37.163</notificationoccurrencedate>
    </notification>
    <notification>
      <notification id="645592820" />
      <notificationtype id="2">Building Construction Completed</notificationtype>
      <notificationoveralltype id="1">Town</notificationoveralltype>
      <notificationtown id="1" />
      <notificationdetail>[@ps=GM Stormcrow|1|DEVS|18|1|0|740-746-755-0-0-0-0-0-0-0-0-0-0|Illyriad Dev Team|Game Master|10-439-294-72] Arctic Warfare College L4 completed at [@t=Stormont|1|383|-1815|12741|1|1|1|51|1|GM Stormcrow|DEVS|1|15-4 wall]. Your building queue is empty.</notificationdetail>
      <notificationoccurrencedate>2015-02-23T01:52:37.183</notificationoccurrencedate>
    </notification>
  </notifications>
</notificationsapi>


(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.

Breaking it down, you have:

  1. The standard Server Identification snippet, followed by

  2. The <player id> who this Key belongs to (so you can match this to the existing Player Data feed) , and the exact key you just used

  3. A list of Notifications that this player currently has in their Notification list, comprising:
  • the <notification id> identifier (this is a bigint linear, incrementing number for all players)

  • the <notificationtype id> which identifies the kind of notification it is along with a textual description (eg "Building Construction Completed"), an int and a varchar(255) respectively.  

  • the <notificationoveralltype id> which identifies the main "type" that the notification is, such as "Town", "Research" or "Military", and is an int and a varchar(255) respectively.

    We'd prefer not to provide a complete lookup list of the two Notification Types, because we do add new notifications quite regularly.  It'd be far preferable for you to build / check your own lookup list from the <notificationtype id> unique identifier, along with the accompanying notification type descriptor.

  • the <notificationtown id> which is the TownID to which the notification is related, that can be looked up in the town table datafeed.  This int field is optional and may be blank for notifications that apply account-wide (such as "Medal Awarded") rather than town-specific.

  • the <notificationdetail> which is a varchar(max) - but in practice will never exceed 8000 chars if you have to limit your field size - and is the identical text that is sent into the browser ingame, including the to-be parsed details usually contained in the square-brackets such as @ps= and @t=.

  • the <notificationoccurrencedate> which is a timestamp on the notification itself, in the format yyyy-mm-ddThh:mm:ss.SSS 

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: 
http://elgea.illyriad.co.uk/external/notificationsapi/elgea-NOTIF-AQAAAGDX3am4eJa9JZU5yiC1aE3XGM0Rkey0dZTCB2Ksfozk7bajd5b22PsV3YbfSoKN5F-JJucBiS8k?LastNotificationID=645592820


... 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
Back to Top
 Post Reply Post Reply
  Share Topic   

Forum Jump Forum Permissions View Drop Down

Forum Software by Web Wiz Forums® version 11.04
Copyright ©2001-2015 Web Wiz Ltd.