Play Now Login Create Account
illyriad
  New Posts New Posts RSS Feed - Combat API and its use in a Player Run Tourney
  FAQ FAQ  Forum Search   Register Register  Login Login

Combat API and its use in a Player Run Tourney

 Post Reply Post Reply Page  123 11>
Author
Cilcain View Drop Down
Wordsmith
Wordsmith
Avatar

Joined: 13 Oct 2012
Status: Offline
Points: 106
Post Options Post Options   Thanks (1) Thanks(1)   Quote Cilcain Quote  Post ReplyReply Direct Link To This Post Topic: Combat API and its use in a Player Run Tourney
    Posted: 11 Apr 2016 at 16:02
In a previous thread regarding the activation of Tournament Squares (http://forum.illyriad.co.uk/tournament-square-update_topic6846_page1.html) some concerns regarding the use of the Combat API for this tournament were raised.  Based on some replies in that thread, and on some messages I have received, I don’t believe there is a wide understanding in the player base of what this API is, and what the concerns are.  So, I thought I would document my understanding of the API, how it works, and things players sharing their API key should be aware of (IMHO).

I think it’s great that the Devs have provided this, and the other APIs, but believe that the running of a server wide player run tourney is a specific scenario that the current API is not suitable for.

 

What is the Combat API?

Without getting too technical, the Combat API is one of a set of computer programs that the Devs have made available to players.  Its job is to return a set of data based upon a ‘key’ that is passed in a request.  The ‘key’ is a big line of characters that is specific to you as a player – you generate this in your Account screen.

How is the Combat API used?

Again, without getting too technical – you (or someone else), can use the API either in a computer program you (or someone else) have written, or even just in a web browser - the API call is essentially just a URL/web address.  The call to the API will require a valid ‘key’ as part of the address.  The API will then return a set of data to the caller containing all of the data corresponding to the ‘key’ provided.

Can I have a go?

Yes.  Generate yourself a Combat API key in the relevant page under your Player Account.  It will begin with “elgea-COMRP-“, and then a long list of random characters.

Next, in a browser’s address bar, enter http://elgea.illyriad.co.uk/external/combatreportsapi/ - and then paste in your API key after the last /.  Press enter, wait a second or two, and you will see the response.  This response is in XML format, but it’s quite easy to read.  It just lists all combats you have been involved in since you generated your API key (so you might want to go and kill some rats, and then try this again).

Each combat is identified with a ‘personalcombatkey id’ – this is another string of random characters contained within quotes.  Next, you need to copy one of these, and paste it onto the end of http://elgea.illyriad.co.uk/external/combatreport/ in your browser address bar, and press enter.  This will now return another set of data with specific details of the combat event you selected.

This is the manual way of using the API, but if you are a reasonable coder, then you can do all this automatically for a large number of players’ APIs (as long as they have provided the keys to you).  The returned XML data can then be automatically split out and stored in a database.

What data is provided by the Combat API?

If you follow the steps above, and read the XML, then you will see what is available – if not, then in summary;

·         Location of combat,

·         Date/Time of combat,

·         Terrain details,

·         Date/Time that your army began moving to the combat square,

·         Length of any occupation following the combat,

·         Defending Player(s),

·         Cities that defending armies come from,

·         Defending alliances,

·         Defending army names,

·         Defending commanders and health,

·         Defending troop types,

·         Defending troop quantities,

·         Attacking Player,

·         City that attacking army came from,

·         Attacking alliance,

·         Attacking army name,

·         Attacking commander and health,

·         Attacking troop types,

·         Attacking troop quantities.

 

If I don’t share my API Key can my data still be accessed?

Yes, in some circumstances.

If you are attacked by someone who has shared their API key, then your data will be returned via their API key (if the attacker is comprehensively crushed, then your data will be limited, as it is in the in-game battle report).

Also, if an Ally, Confed or NAP player reinforces a square or city you occupy, then their API key will return data on ALL the armies (including troop type and quantities) for ALL other players on that square/city.

What happens if I share my API Key for a Player Run Tournament?

If you want to take part in a player run ‘King of the Hill’ style tournament, then there is currently no alternative to you supplying the organiser with your Combat API key.

However, there are some considerations you should be aware of;

1.       Do you know exactly who will have access to this data?  It is unlikely to be just one person, as putting together a tournament is a lot of work,

2.       To run a KotH tournament, only a small subset of the data returned by the Combat API is actually needed – are you happy that the organisers will have access to all the other data too?

3.       The data returned by the Combat API is not restricted to tournament squares – therefore, data from any other combat engagement you are involved in outside of the tournament will be available to the organisers too,

4.       If we have multiple player run tournaments over time, then the group of players with access to your data (either static historic data, or live up to date data) will grow.

 

What protection is there against my data being available to others?

Number one is – don’t generate and share you API key.  However, as stated above, currently if you want to take part in a KotH tournament, this isn’t an option.

You can set your military activity to be ‘covert’ by ticking the relevant box before sending each army out – this keeps the resulting data out of your API.  But if you do this for tournament related activity, then it will compromise your involvement in the tournament.

You can also regenerate your Combat API key.  This will immediately render any previously shared key as invalid – again, if you do this during a tournament, it will compromise your involvement.  Also, regenerating your API key does not make existing ‘personalcombatkey id’ values mentioned above invalid – so people could still access your historical combat data – they just wouldn’t get any new ‘personalcombatkey id’ values after you regenerate your key.

If you get attacked/reinforced by someone who has shared their key, then there’s not much you can do to protect your data.

 

What could be done with all this data?

The organisers of the forthcoming tournament have stated that they are only interested in data required to run the tournament – and I have no reason to doubt this.  I expect that future tournament organisers will also say the same thing.

But let’s just imagine that somehow, at some point in the future, a database containing data from hundreds/thousands of players’ Combat APIs falls into the hands of someone who wishes to act against you in the game.

If the database contains data about you and your alliance, then the person with the database would quite easily be able to form a picture of which cities specialise in what troop types, and also the approximate capacity of troops each city can support.  Even if you regenerated your API Key after a tournament ends, then the static data residing in the database will probably still be valid – after all, how often do you change a city’s troop specialisation?

Also, if you and your alliance are defending a square for whatever reason, then it will only need one defender on the stack to have a shared and active API Key for someone with that key to see exactly what troops are on that square.

 

Trust?

In the other thread where this topic was discussed, a number of posters said something along the lines of “what’s the problem as long as you trust the tournament organiser?”

I believe that trust in the tournament organiser is irrelevant – and when I say “tournament organiser”, I mean current and future organisers (including me, if I ever take on the task of arranging a tournament).

The best way of demonstrating that someone has not leaked data (accidentally or otherwise), is to prove that they did not have access to that data in the first place – if you can do that, then it’s instantly ‘case dismissed’.  By using the current Combat API, then this proof is not possible – in fact, it would prove the opposite.

Next, if someone does need access to data, then that person(s) needs to be clearly identified and the number of people kept to a minimum.  Even with the forthcoming tournament, I don’t know exactly who will have access to the API Keys – I know of two names, but I’m sure there must be more.  Even if I was given a list of names and all their alts, there is no way to restrict the use of my key to the people on that list.  And as we get to a second, third, fourth player run tournament, then the picture just gets even more blurred.

Also, trust is transient.  Can anyone guarantee to me, that someone I trust with this data now (or in future tourneys), will not at some point in the future be in an alliance that wants to declare war on me?

 

Can the above concerns be resolved?

Yes.  And hopefully, GM Storm Crow is already on the case, as per his previous post in the forum (in the thread linked above).  If the Devs were to introduce a new API type – let’s call it ‘Tourney API’, then this API could be built such that;

·         It only returned data from combat occurring on the defined tournament squares,

·         It only returned the data required to run a KotH type tournament (which I believe to be Player Name, Alliance Name, Occupation Time, Combat Date/Time, Number of Casualties).

This would then address all of the concerns above whilst supporting the running of much needed tournaments.

 


Back to Top
Rill View Drop Down
Postmaster General
Postmaster General
Avatar
Player Council - Geographer

Joined: 17 Jun 2011
Location: California
Status: Offline
Points: 7078
Post Options Post Options   Thanks (0) Thanks(0)   Quote Rill Quote  Post ReplyReply Direct Link To This Post Posted: 11 Apr 2016 at 17:13
Thank you for posting this, Cilcain.

I also really hope that the developers will develop this new key in time for the tournament.  I also hope they think about the possibility of generating time-limited API keys in the future.  

One of the things I didn't realize when API keys were introduced was that any new generated API will still pull ALL historical data since the date ANY API key was first generated.  This is not a problem for me personally since my combat participation is trivial, but I can imagine in the long run that people will not wish to share EVERY combat they have ever been present at (perhaps since first generating an API key years before) merely for the opportunity to participate in a current event.

I urge the developers to consider alternatives to limit the information accessible by creating keys that would restrict date ranges, for example.  These would not have to be customizable; even something that only pulled for data after January 1 of the current year or something similar would be desirable.

That said, developing a tourney-specific API key as Cilcain described that only pulls data for tournament squares would address this concern for the current tournament and should be a top priority.

Thank you!
Back to Top
Mahaut View Drop Down
Wordsmith
Wordsmith
Avatar

Joined: 20 Jan 2012
Location: North West UK
Status: Offline
Points: 173
Post Options Post Options   Thanks (0) Thanks(0)   Quote Mahaut Quote  Post ReplyReply Direct Link To This Post Posted: 11 Apr 2016 at 20:56
Dear lord this API thing is a mess.

So if I am reading this correctly........

Even without player run tourneys

If a player has used an API and that persons troops are used for any operation whatsoever then you are running a massive risk that all the above data will be available outside the alliance, due to confed or naps it could be anyone from outside the alliance as well or whoever is doing the attacking.

No point in scouts, just have a troop with an API on a tile from a spy account, an alliance tourist or even just a nap or confed that might not even know the API is running in one of their players accounts. Alt accounts not in the same alliance - forget it. 

Just made spy accounts even more important, scouts pointless, naps and confeds something to be viewed with great suspicion whenever anything goes awry. In fact made even HAVING naps and confeds something to really be looked at very very carefully.

Jeez

Why don't we all just publish our troop numbers and what we make where on the forums and save everyone the bother of looking it up. Then we can all go play farmville
 - after all we aren't playing a strategy game anymore, we're playing a "who has good coders in their alliance" game instead. 

What on earth were the devs thinking when they released this?
Back to Top
Excession View Drop Down
New Poster
New Poster


Joined: 30 Jan 2012
Status: Offline
Points: 12
Post Options Post Options   Thanks (0) Thanks(0)   Quote Excession Quote  Post ReplyReply Direct Link To This Post Posted: 11 Apr 2016 at 22:12
Truth is that player led Tourneys are a great addition to the tradition of Tourneys of the traditional form but should not be a way for the game escaping the effort of running them for the players. As a long term player that thrived on Tournaments I've found myself increasingly disappointed by the lack of them. It would be true to say I was lured to this game by them, a kinda end game but without having to start again. So I have this to say to the game's custodians. "Sort the API for player led tourneys to work properly and securely and get you fingers out and run one for the players yourselves". ATM this is getting like a restaurant where the customer is expected to cook for themselves and then clear up afterwards.
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: 11 Apr 2016 at 23:52
Originally posted by Mahaut Mahaut wrote:

What on earth were the devs thinking when they released this?

We were thinking that, for example, an alliance might find it useful to keep track of the progress of a war., with realtime combat reports from the members of the alliance who shared the key with their leadership  

The API key system has been out there - and used by many highly successful alliances - for many years - since well before the player-run tournaments idea.

The 'key' thing, which I think you might be missing, is that *you can choose to whom you give your API key*.  If you don't want someone finding out your super-sekret battle reports, don't give them your API key.  Plus you can revoke it at any time of your choosing.  If you don't like the idea of the API key, then don't share yours with anyone.  Problem solved.

Originally posted by Mahaut Mahaut wrote:

Dear lord this API thing is a mess.
The API key system is a hugely useful and massively extensible system.  It is not a "mess".  Your understanding of it and it's possible uses and purposes, however, most definitely is.

Regards,

SC


Back to Top
Mahaut View Drop Down
Wordsmith
Wordsmith
Avatar

Joined: 20 Jan 2012
Location: North West UK
Status: Offline
Points: 173
Post Options Post Options   Thanks (0) Thanks(0)   Quote Mahaut Quote  Post ReplyReply Direct Link To This Post Posted: 12 Apr 2016 at 00:28
I can choose to whom I give my API key. I however have no control over who else hands out theirs in a war or a tourney (player run ones I can't even enter if not sharing) and is on the same tile.

and as for not sharing my super-sekret[sic] battle reports...well why would I? How many games have you played that dish out that information to all and sundry?

"The API key system has been out there - and used by many highly successful alliances - for many years - since well before the player-run tournaments idea."  Really? The existing one was released Feb 2015, the previous one didn't have the same amount of data and wasn't so accessible


Edited by Mahaut - 12 Apr 2016 at 01:37
Back to Top
Excession View Drop Down
New Poster
New Poster


Joined: 30 Jan 2012
Status: Offline
Points: 12
Post Options Post Options   Thanks (0) Thanks(0)   Quote Excession Quote  Post ReplyReply Direct Link To This Post Posted: 12 Apr 2016 at 00:48
SC I note you made no response to my post.
Back to Top
Excession View Drop Down
New Poster
New Poster


Joined: 30 Jan 2012
Status: Offline
Points: 12
Post Options Post Options   Thanks (0) Thanks(0)   Quote Excession Quote  Post ReplyReply Direct Link To This Post Posted: 12 Apr 2016 at 00:52
I'd say the key thing is if I can be bothered to play a deeply flawed game!


Edited by Excession - 12 Apr 2016 at 00:52
Back to Top
Dungshoveleux View Drop Down
Postmaster
Postmaster


Joined: 09 Nov 2013
Status: Offline
Points: 958
Post Options Post Options   Thanks (1) Thanks(1)   Quote Dungshoveleux Quote  Post ReplyReply Direct Link To This Post Posted: 12 Apr 2016 at 01:07
I would suggest all involved to take a deep breath, step back, and wait for the revised api key which limits the information shared to acceptable levels for most people.  Give the devs space to fix this which I am sure, having got their attention, they will.
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 (1) Thanks(1)   Quote GM Stormcrow Quote  Post ReplyReply Direct Link To This Post Posted: 12 Apr 2016 at 01:18
Originally posted by Mahaut Mahaut wrote:

How many games have you played that dish out that information to all and sundry?

Eve Online is a great example of a combat API key in use.

And it's not 'to all and sundry': it's to those whom you choose to share your API key with - just like it's to those whom you choose to forward on your combat reports to.  

It's your choice.  

No one is forcing you to share your API key.  

No one is forcing you to forward your combat report emails. 

Regards,

SC
Back to Top
 Post Reply Post Reply Page  123 11>
  Share Topic   

Forum Jump Forum Permissions View Drop Down

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