CAKs and Contracts in the API

[CCP]

CAKs and Contracts in the API
7 September 2011, 5:57 pm

 For a while now we've had the latest API updates running on a SISI setup on apitest.eveonline.com as well as the new key management web on supporttest.eveonline.com. Most of you API-savvy programmers probably know how the new toys work to every last detail, but I'm still going to spell them out just to make sure everything is clear.

 

Customizable API Keys

You've been asking for this one for a while now and here it is. The new API key system offers a variety of new features that we hope will fill both third-party developers' and third-party application users' hearts with light, joy and furry little animals.

• Up to 10 API keys per account
• Customizable access to the API + Templates
• Optional expiry date
• Access to character- and corporation information separated
• Single-character or account-wide keys

The concept of customizing your API keys is all about being able to control what information can be accessed in the API with a particular API key, and for how long. Say you want to give the director of your corporation access to your wallet info but only for today, you can create a key that only unlocks that information and expires tomorrow. When you quit your corporation you can cut off any access to your API information your former boss may have had without having to create a new key for your third-party apps.

You can also customize the key's access to API information based on characters. If you select one of your characters then the key will only apply to the selected one, if you don't the key will provide access to all your characters' info. If you have a character that's a CEO or a corporate director then you can create a corporation key which unlocks the character's corporation information.

By templates, we mean that third-party developers can provide users with links to the API key creation form with a pre-defined access mask which describes what is needed for their application to work properly and the required API pages will be selected automatically on the form.

The management web for API keys has been moved to the EVE Support website. The old one will, however, remain open and you can still create and use the old keys in the API for a while. We don't have an exact date for cutting them off; we want to give developers plenty of time to make the switch and make users aware of the changes, but we are measuring this in weeks and considering something in the order of 4-8 weeks. We'll keep an eye on the key usage though and let you know well before we flip the switch.

To use the new keys in the API you can throw out the old userID and apiKey URL parameters and use keyID and vCode instead. You can find the keyID in the first column (called ID) on the API key management website, vCode stands for Verification Code and is displayed in the same table for each key.

Technical information in CCP Stillman's dev blog from the testing period of the new keys still stands. You can find some examples of how to use the keys in the API and how to create the template/predefined links there.

 

Contracts

Here's another popular request from the API community. I posted a dev blog a while ago which explains the strategy we were going with at the time. To make a long story short, we decided to stick with that strategy.

We created three new pages to display contract information. Well, three pairs of pages since you can fetch character and corporation contracts.

/char/Contracts.xml.aspx: Lists contracts issued within the last month as well as all contracts marked as outstanding or in-progress. A single contract can be retreived using the contractID parameter. Each item in the list has the following attributes:

• contractID
• issuerID: The character who issued the contract.
• issuerCorpID: The corporation of which the issuer was a member of when the contract was issued.
• assigneeID: The character or corporation who was assigned to the contract, 0 if none.
• acceptorID: The character who has accepted the contract, 0 if none.
• startStationID
• endStationID
• type: Can be "ItemExchange", "Auction", "Loan" or "Courier".
• status: Can be "Outstanding", "InProgress", "CompletedByIssuer", "CompletedByContractor", "Completed", "Cancelled", "Rejected", "Failed", "Deleted" or "Reversed".
• title: The player-made description. Odd naming, we know.
• forCorp: 1 if the contract was issued on behalf of the issuer's corporation, 0 otherwise.
• availability: Can be "Public" or "Private". The availability can also be set to "My Corporation", in that case the availability here is "Private" and the assigneeID is the corporation of which the issuer was a member of when the contract was issued.
• dateIssued
• dateExpired
• dateAccepted: Empty if the contract hasn't been accepted.
• numDays: Days to complete the contract.
• dateCompleted: Empty if the contract hasn't been completed.
• price
• reward
• collateral
• buyout
• volume

/char/ContractItems.xml.aspx: Lists items that a specified contract contains, use the contractID parameter to specify the contract. Note that items for courier contracts are not displayed. Each item in the list has the following attributes:

• recordID: A unique key.
• typeID: The type of the item.
• quantity: The actual quantity.
• rawQuantity: This attribute will only show up if the quantity is a negative number in the DB. Negative quantities are in fact codes, -1 indicates that the item is a singleton (non-stackable). If the item happens to be a Blueprint, -1 is an Original and -2 is a Blueprint Copy.
• singleton: 1 if this is a singleton item, 0 if not.
• included: 1 if the contract issuer has submitted this item with the contract, 0 if the isser is asking for this item in the contract.

/char/ContractBids.xml.aspx: Lists the latest bids that have been made to any recent auctions. The first request lists all bids made to last months auctions but subsequent requests will only display bids that have been made since that last request. The item attributes are pretty straight forward:

• bidID: A unique key.
• contractID
• bidderID
• dateBid
• amount

These pages are accessible with character keys. The /corp folder has identical pages accessible with corporation keys. The data retrieval differs slightly but the datasets returned by the API are same as in the /char folder.

 

Random stuff

• Items in the AssetList (and ContractItems) now include a rawQuantity attribute if the quantity in the DB is negative. Negative quantities are in fact codes, -1 indicates that the item is a singleton (non-stackable). If the item happens to be a Blueprint, -1 is an Original and -2 is a Blueprint Copy. For further information about negative quantities see this devblog.
• MarketOrders.xml.aspx will now return all active orders plus all orders issued in the last 7 days. An optional "orderID" parameter can be provided to fetch any order belonging to your character/corporation.
• CharacterInfo.xml.aspx now includes employment history.
• WalletJournal.xml.aspx should no longer cause a Scotty when rowCount is high.

Credits

I think it's only fair to mention that CCP Prism X and CCP Stillman did the bulk of the work on the customizable API keys. All I did was marvel at this godly construct and build a couple of minor additions to it.

So. Thanks for reading, I know it was boring and dry as usual and for that I'm not sorry. I'll see you guys on the forums.

CCP Elerhino

 



Source: eveonline.com | devBlog