Dominion - API

[[FUN] Filz]

Dominion - API
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

 

 



 



Source: eve-online.com | devBlog