Combat API and its use in a Player Run Tourney |
Post Reply | Page 123 11> |
Author | ||
Cilcain
Wordsmith Joined: 13 Oct 2012 Status: Offline Points: 106 |
Post Options
Thanks(1)
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. |
||
Rill
Postmaster General Player Council - Geographer Joined: 17 Jun 2011 Location: California Status: Offline Points: 7078 |
Post Options
Thanks(0)
|
|
Thank you for posting this, Cilcain. 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!
|
||
Mahaut
Wordsmith Joined: 20 Jan 2012 Location: North West UK Status: Offline Points: 173 |
Post Options
Thanks(0)
|
|
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?
|
||
|
||
Excession
New Poster Joined: 30 Jan 2012 Status: Offline Points: 12 |
Post Options
Thanks(0)
|
|
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.
|
||
GM Stormcrow
Moderator Group GM Joined: 23 Feb 2010 Location: Illyria Status: Offline Points: 3926 |
Post Options
Thanks(0)
|
|
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.
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 |
||
Mahaut
Wordsmith Joined: 20 Jan 2012 Location: North West UK Status: Offline Points: 173 |
Post Options
Thanks(0)
|
|
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 |
||
|
||
Excession
New Poster Joined: 30 Jan 2012 Status: Offline Points: 12 |
Post Options
Thanks(0)
|
|
SC I note you made no response to my post.
|
||
Excession
New Poster Joined: 30 Jan 2012 Status: Offline Points: 12 |
Post Options
Thanks(0)
|
|
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 |
||
Dungshoveleux
Postmaster Joined: 09 Nov 2013 Status: Offline Points: 958 |
Post Options
Thanks(1)
|
|
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.
|
||
GM Stormcrow
Moderator Group GM Joined: 23 Feb 2010 Location: Illyria Status: Offline Points: 3926 |
Post Options
Thanks(1)
|
|
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
|
||
Post Reply | Page 123 11> |
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 |