Why Not a Lightweight Library?

The minimum library interface is a strawman, brought up to be discarded. A library could provide procedures to: open a socket to the IB tws; send and receive handshake information; send data aquisition, order, and account related requests in accordance with the api, and in response to procedure calls; and store the resulting messages as events, to be forwarded, again in response to a library call. This buys us little, and costs us much.

To see how little we gain, consider a transparent standalone program for the IB tws api, one that reads and forwards handshake and other requests upstream, and similarly messages to the downstream, transferring both as is. It adds an extra layer, and no additional functionality whatsoever; clients must have full knowledge of the tws api to use it, and given that, could just as well connect to the IB tws directly.

Note, then, the two problems that arise to the extent that we strive for a ``thin'' interface: little or no additional functionality, and at the cost either of yet another new binary api on top of the old, or at best a pointless interface layer. Obvious though these problems may be, they're hard to avoid: any programmatic interface to the IB tws api must be carefully designed if it is to simplify access to the api without sacrficing functionality.

The minimum library would replace a protocol api, admittedly binary but still a language of requests and messages amenable to formal specification and open to programs in any language, with request and message procedures for each protocol event, and with an interface every bit as large as the initial IB tws api. Clients need nearly full knowledge of the base api, and there is a maintenance headache as well. The event procedure parameter objects and the primitives to lay their attributes out on the wire must accord with the api, and yet testing those procedures for api conformance is hard, so hard in fact, that other free software projects taking this approach have bogged down. There are twin problems of scale, and efficiency: testing the correctness of the parts is individually straight-forward but collectively onerous; and there is little to the library besides the (large) interface, so that downstream clients are unnecessarily complex, due both to the bulk of library-facing code, and the need to manage low-level api state.

I claim that maintainable interface software to the IB tws api must include table driven specification of the protocol events, with the request send and message receive processing driven by those table entries; that the downstream client must be able to offload knowledge of api details to stored, shared tables, i.e. a database; and that the interface must shield the client from api state, and take responsibility for api event state where feasible. In any case, I refused to wade into the maintenance swamp of one-per-event api send and receive procedures when I started the shim, and I reject it even more firmly today, after having watched other projects struggle with this headache.

Bill Pippin 2010-01-14