Contracts in the API

[CCP]

Contracts in the API
29 July 2011, 2:36 pm

Hello!

We have been working on a new set of API pages that will give you access to Contract information. This functionality is due for a late August deployment but we wanted to get an early devblog out there to introduce our ideas and get some feedback from the experts on the other end.

The Problem

Contracts and Market Orders are very similar, and have caused us similar headaches, in terms of how do we give API consumers usable information without causing too much strain on the EVE datastore. What we wanted to do was conceptually simple, we wanted to give you non-expired items as well as items that expired less than X time ago. But it turns out we can't do this without taking an axe to the datastore because, without getting into details, the datasets simply aren't optimized for this kind of a query.

A Solution

So we decided to try a different approach and fetch only active non-expired items. This is what we did with the Market Orders to limit the amount of un-needed information the API needs to query for and forward to clients. This greatly improved the query for the datastore but shot API clients in the foot because we took away vital information.

One issue is that orders that are issued and processed within the API Orders cache period never appear in the API. To bridge this gap we want to include recently issued orders in the list. We're thinking a week's worth of orders would not only fix the problem but also come in handy if you only want to get the list once a day or every few days.

Another issue is that when an old order gets processed it disappears off the list without any mention of what happened to it. To fix this we'll add an API page, or perhaps an orderID parameter to the Market Order page, so that you can look up the missing order and find out what happened to it.

Contracts

Similar to the Market Orders, the Contract list will contain contracts that are outstanding or in progress, as well as recently issued contracts. We'll also have a separate page or a contractID parameter so that you can look up a single contract.

Actually there will be two sets of Contract pages, one for characters and another one for corporations. The character version will give you contracts that the character is attached to in one way or another. The corporation version will show you contracts that your corporation or alliance is attached to and you'll need a corporation key to access it. This is something we wanted to get your opinion on, the corporation contracts are visible in-game to any member of the corporation but in the API we're locking it behind a corporation key which only directors and CEOs can create. This is a kind of a security measure in the sense that it prevents members from accidentally giving corporate information to a 3rd party.

The contract lists themselves will not include items, bids or notifications. We'll have separate pages for items and bids but most likely completely skip notifications. The item page will display a list of items for a specified contract, the information will contain things like type ID, quantity and whether the item is being asked for or is included.

The bids page will be a bit different. It will display a list of recent bids on a character/corporation basis. Each time the cache is refreshed you'll get a list of bids that have been made on contracts issued by your character/for your corporation since the last time the cache was refreshed. The first time you request the bid list it will give you all bids since yesterday (relatively speaking).

 

A quick note on the deployment schedule - we wanted to get the Market Order fixes out ASAP but currently we don't have a deployment scheduled before the late August one. To take an API build from a development stage to deployment involves a number of people in a number of departments and it's very difficult to get anything like that coordinated during holiday seasons. So most likely you'll have to wait for that one.

- CCP Elerhino



Source: eveonline.com | devBlog