Dominion - API (http://www.eveonline.com/devblog.asp?a=blog&bid=716)
24 November 2009, 11:56 am
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
(http://s9.addthis.com/button1-share.gif)
Source: eve-online.com | devBlog (http://www.eve-online.com/)