3-23-98

THE AUCTIONBOT API
------------------
The Michigan Internet AuctionBot API (API) is a client/server
communication protocol for a network API.  Our protocol is
sufficiently simple and easy to implement for client developers in any
language on any platform.  By implementing the API specification,
developers can interact with the Auction server as they would do
through the web interface, but with software agents.  This makes it a
useful device for agent researchers exploring the design space of
auction mechanisms, as well as developers interested in implementing
automated auctions using the AuctionBot.

We supply a C/C++ implementation of the the API specification for
developers.  Implementing the API in other languages is very 
straightforward.

WHAT'S NEW
----------
3-16-98
 * Added two new api services, servertime and transidforauction.
 * Added order keyword for services that support ordering. If no
   order keyword is specified, the order is set to a default value.
   The default is listed in api_operations.txt.
 * Changed keyword "username" to "name" in auth

3-20-98
 * Added "hypotheticalquantitywon" and "activebidid" to getquote return
   string
 * Added "bidid" to submitbid


GETTING STARTED
---------------
If you do not have an account with the AuctionBot please create one
from "http://auction.eecs.umich.edu/newacct/accountApplication.html/".
This is necessary to use the API and run the example program.

First, you have to make the API support files and example program.
Open the makefiles in the 'APICommon' and 'APIClient' directories and
change 'CC' and 'CCPP' to your C and C++ compiler. If necessary,
uncomment the line:

LIBS = -lsocket -lnsl

in the makefile in the APIClient directory.

Next, change to the 'APIClient' directory and execute 'make all'.

If all goes well you should have a built program called "example"
that can be run.  The example program is intended to show some of the 
features  of the API.  The program functions in two modes; interactive
and automated.  In interactive mode, the program reads user commands,
in this case API string messages, sends them to the server and echos  
the string sent from the server.  In automated mode, the user passes
the program a file name from the command line containing a series of 
API string messages.  The client program reads each message,
sends it to the server and echos the return string.  

The file 'example.txt' is included to show the automated mode. 
Open the file and change the username and pw labels to your username
and password. Save the file and execute:

  example example.txt

This program will read the commands in the file 'example.txt', write
them to the server, read the server response, and echo the results. 


OVERVIEW OF THE API DESIGN
--------------------------
Our main design goals for the client API were correctness, ease of
use, simplicity, platform independence and the use of standardized  
interface languages.  The current API is the product of several years
of revision, guided by the results of large-scale classroom exercises
and careful deliberation over design issues.  

All messages are encoded in the common URL format.  We choose this
format for two reasons; (1) we had working code that parsed URL-based
messages already and (2) why force the user, and us, to learn yet
another message format.

Example string passed to the server:

     auctioninfo?auctionid=7

Example string returned from the server:
  
    auctioninfo?id=7&owner=1&type=1&auctionstatus=1&name=TestAuction
    &description=This auction allows users to try out their accounts
    and make test bids.  Please note that, for this auction only,
    no goods are being bought or sold and transaction notifications
    are NOT binding commitments for any sort of trade.&url=
    &timecreated=843771517&numbuyer=2&numsellers=2&hasdiscretegoods=1
    &membership=0&quotemode=2&quotepolicy=3&quoteinterval=3600
    &quoteincrement=0&quoteschedule=&nextquotetime=887038875
    &lastbidprice=110100&lastaskprice=-100&lastquotetime=887035275
    &lastclearprice=1107&lastcleartime=884800717&clearpolicy=0
    &earliestfinalclear=858636000&intclearmode=2&intclearinterval=10800
    &intclearschedule=&finalclearmode=5&finalclearinterval=0
    &finalcleartime=1136048399&nextcleartime=887036317&bidrules=1
    &tiebreaking=4&catalogkey=&group=0&notifications=pq
    &revelation=nNT     &goodunits=1000&status=0

Every string sent from the server will have a status label and value
indicating if the operation succeeded or failed.  Zero indicates
success, > zero indicates failure.  See the file
'docs/api_operations.txt' for information on the return codes, as well
as the supported operations and string formats.

The connection function SetupConnection returns 0 on no error and < 0 
on error. ReadAPIString and WriteAPIString both return the number of
bytes read or written.


CONTACTING US
--------------
If you encounter any problems, or have comments, please send them to
omalley@umich.edu. 

The API WWW page is located at:

  http://auction.eecs.umich.edu/api/index.html