Dominion - API
Hello gang, I'll get right to the point.
As you probably know already, the sovereignty system is getting a new haircut in the Dominion expansion, switching from mohawk to spikes. Relevant API pages have been altered to reflect the change of style. In short, some rowset columns have been removed, one added and one full new page added.
/map/Sovereignty.xml.aspx
This page lists solar systems and their sovereignty information. We've removed constellationSovereignty and sovereigntyLevel and added corporationID. The corporation ID indicates the company which owns the Territorial Claim Unit (TCU) if there is one in the system. We've also lowered the caching time of this page from six hours to one and, since sovereignty changes will happen when they happen (not just during down-time), the age-old problem of out-dated sovereignty information should be a not-so-glorious part of EVE's glorious history.
/map/SovereigntyStatus.xml.aspx
This new page lists all sovereignty structures in EVE in a rowset which has the following columns: structureID, solarSystemID, structureTypeID, ownerID, state, startTime, completionTime. The start- and completion timestamps indicate when the structure's current state began and when it will end. If the state doesn't call for timestamps then they are empty. For a list of all possible states, see the appendix below.
/corp/StarbaseDetail.xml.aspx
This one displays information on a specific station. We've removed claimSovereignty flag.
Further additions to the sovereignty part of the API are planned, see discussions on this thread.
Another big change brought forth by His Mightyness the Dominion is an updated mail system. Not only has it been updated but also split in twain by a group of heavy machinery wielding, Rammstein loving meta-astronauts calling themselves And there will be Cake, adding a notification system to which all server-generated mails (agents, bills, etc.) will be directed.
So. We've added both systems to the API. The data structure is similar in both systems so we used the same technique to access them via the API. To pre-emtively break some hearts - the API will not give you any mail bodies or detailed notification information, nor will you be able to send mail through the API. You will not be able to page through your mail/notifications like the wallet pages allow. This is an API feature that is likely to be under heavy bombardment so we've had to contain our enthusiasm for pleasing the crowd quite a bit. At least for now. Let me attempt to explain how this works.
Both pages require a user ID, full access API key and a character ID. Both pages display a single rowset. The pages are called:
- /char/MailMessages.xml.aspx - columns: messageID, senderID, sentDate, title, toCorpOrAllianceID, toCharacterIDs, toListIDs, read
- /char/Notifications.xml.aspx - columns: notificationID, typeID, senderID, sentDate, read
Most of the columns are self-explanatory but a few are worth mentioning:
- toCorpOrAllianceID - The ID of a corporation/alliance that the mail was sent to.
- toCharacterIDs - Comma-separated list of characters that the mail was sent to.
- toListIDs - Comma-separated list of mailing lists that the mail was sent to. Currently you can only send a mail to one list but that might change so we made this a list instead of a single ID. See below for more info on mailing lists.
- read - Whether the mail/notification has been read in the EVE client. This does not change when you get it through the API. This is a boolean, values will be 0 or 1.
- typeID - The notification type indicates what has happened but not who performed the action in question nor upon whom the action was performed. For a list of type IDs and descriptions, see the appendix below.
Here's how the paging/caching (or actually the lack thereof) works:
- The first request returns the latest 50 mails/200 notifications received by the character within the last week. Older items are skipped.
- Subsequent requests return only new items that the character has received since the last request.
- You can request new items every 30 minutes.
- If you want to re-set the timer and get the first-request bulk again, you'll have to wait 6 hours.
The idea is to provide just enough information for 3rd party applications to have a pop-up feature with an indicator of what's going on, you'll have to log in to the game for the details. At least for now.
The full new page that we added is /char/mailinglists.xml.aspx which lists all mailing lists the character is currently a member of. Like the other pages it has a single rowset with columns listID and displayName.
Apart from the feature related changes and additions we've been working on some optimizations to ease the chokehold the API has on the server. These are all behind-the-scenes changes that you don't need to know about so I'm not going to tell you because I can't kill you with this dev blog.
On a more general note, usage of the API via 3rd party applications and servers is constantly growing. Roughly estimated, the API servers are now receiving around 2000 requests per second which is quite an increase from my last dev blog. When considering additions to the API we always have to make the performance impact on the EVE cluster a primary concern and we're constantly on the lookout for heavy queries and other trouble makers. So far we're in good shape but there's still plenty of work to do on the optimization end.
We hope you can put these additions to good use and we'll be watching the forums for feedback.
Appendix - Sovereignty Structure States
- 0 - Unanchoring or unanchored.
- 1 - Anchoring or anchored.
- 2 - Online and has not consumed resources yet.
- 3 - Online and in the process of consuming reinforced resources.
- 4 - Online and in the process of consuming online resources.
- 5 - Online and in the process of the structures specialised operation of choice.
- 6 - Online and in a vulnerable state.
- 7 - Online and in Shield reinforcement.
- 8 - Online and in Armor Reinforcement.
- 9 - In an invulnerable state.
Appendix - Notification Types
- 2 - Character deleted
- 3 - Give medal to character
- 4 - Alliance maintenance bill
- 5 - Alliance war declared
- 6 - Alliance war surrender
- 7 - Alliance war retracted
- 8 - Alliance war invalidated by Concord
- 9 - Bill issued to a character
- 10 - Bill issued to corporation or alliance
- 11 - Bill not paid because there's not enough ISK available
- 12 - Bill, issued by a character, paid
- 13 - Bill, issued by a corporation or alliance, paid
- 14 - Bounty claimed
- 15 - Clone activated
- 16 - New corp member application
- 17 - Corp application rejected
- 18 - Corp application accepted
- 19 - Corp tax rate changed
- 20 - Corp news report, typically for shareholders
- 21 - Player leaves corp
- 22 - Corp news, new CEO
- 23 - Corp dividend/liquidation, sent to shareholders
- 24 - Corp dividend payout, sent to shareholders
- 25 - Corp vote created
- 26 - Corp CEO votes revoked during voting
- 27 - Corp declares war
- 28 - Corp war has started
- 29 - Corp surrenders war
- 30 - Corp retracts war
- 31 - Corp war invalidated by Concord
- 32 - Container password retrieval
- 33 - Contraband or low standings cause an attack or items being confiscated
- 34 - First ship insurance
- 35 - Ship destroyed, insurance payed
- 36 - Insurance contract invalidated/runs out
- 37 - Sovereignty claim fails (alliance)
- 38 - Sovereignty claim fails (corporation)
- 39 - Sovereignty bill late (alliance)
- 40 - Sovereignty bill late (corporation)
- 41 - Sovereignty claim lost (alliance)
- 42 - Sovereignty claim lost (corporation)
- 43 - Sovereignty claim aquired (alliance)
- 44 - Sovereignty claim aquired (corporation)
- 45 - Alliance anchoring alert
- 46 - Alliance structure turns vulnerable
- 47 - Alliance structure turns invulnerable
- 48 - Sovereignty disruptor anchored
- 49 - Structure won/lost
- 50 - Corp office lease expiration notice
- 51 - Clone contract revoked by station manager
- 52 - Corp member clones moved between stations
- 53 - Clone contract revoked by station manager
- 54 - Insurance contract expired
- 55 - Insurance contract issued
- 56 - Jump clone destroyed
- 57 - Jump clone destroyed
- 58 - Corporation joining factional warfare
- 59 - Corporation leaving factional warfare
- 60 - Corporation kicked from factional warfare on startup because of too low standing to the faction
- 61 - Character kicked from factional warfare on startup because of too low standing to the faction
- 62 - Corporation in factional warfare warned on startup because of too low standing to the faction
- 63 - Character in factional warfare warned on startup because of too low standing to the faction
- 64 - Character loses factional warfare rank
- 65 - Character gains factional warfare rank
- 66 - Agent has moved
- 67 - Mass transaction reversal message
- 68 - Reimbursement message
- 69 - Agent locates a character
- 70 - Research mission becomes available from an agent
- 71 - Agent mission offer expires
- 72 - Agent mission times out
- 73 - Agent offers a storyline mission
- 74 - Tutorial message sent on character creation
- 75 - Tower alert
- 76 - Tower resource alert
- 77 - Station aggression message
- 78 - Station state change message
- 79 - Station conquered message
- 80 - Station aggression message
- 81 - Corporation requests joining factional warfare
- 82 - Corporation requests leaving factional warfare
- 83 - Corporation withdrawing a request to join factional warfare
- 84 - Corporation withdrawing a request to leave factional warfare
