An API for Internet Auctions

Kevin and Terence are members of the Advanced Technology Labs at the University of Michigan. They can be contacted at omalley@ umich.edu and [email protected], respectively.

According to forecasters, U.S. electronic commerce revenues will grow from $8 billion in 1997 to $327 billion in the year 2002. This projected growth has inspired many companies to invest substantial effort and money into making goods available over the Internet. Of the different approaches to e-commerce, one of the fastest growing involves online Internet auctions.

There are currently hundreds of Internet auction sites, ranging from those selling antiques and wine, to others for computer hardware and software. In addition to the commercial use of online auctions for selling goods, the study of auction mechanisms and auction theory is being applied to traditional research problems in computer science. A relatively new area of study, for instance, is the use of computational markets for allocating resources dynamically and effectively in multiagent and distributed systems.

Ideally, the auction service should provide a mechanism that gives users the ability to easily automate auction-related tasks, such as creating auctions, submitting bids, and monitoring auctions. The Michigan Internet AuctionBot API (available at http://groucho.eecs.umich.edu/ marx-pub-software/ and from DDJ; see "Resource Center," page 3) was developed to address this issue.

The Michigan Internet AuctionBot (http://auction.eecs.umich.edu,) developed at the University of Michigan Artificial Intelligence Laboratory, is a freely available auction service that supports both software and human agents. For over two years, we've used it to sell goods and perform auction experiments. Typical online auctions offer only one or two basic auction types, despite the diversity of market protocols you find in the real world. Since we believe that designers of electronic marketplaces will draw from numerous protocol options, the AuctionBot is highly configurable and supports a wide range of auction protocols.

The AuctionBot API is a client/server communication protocol that is straightforward to implement for client developers in any language on any platform. By implementing the API specification, you can interact with the Auction server as you would do through the web interface, but with software agents. This makes it useful for agent researchers exploring multiagent systems, as well as developers interested in implementing automated auctions using the AuctionBot.

API Design Criteria

Our design goals for the client API include correctness, ease of use, simplicity, platform independence, and the use of standardized-interface languages. The code must be correct, because the Auction- Bot helps clients compute monetary prices for goods, and where money is at stake, the answer must be right every time. The API must be easy to use because it is intended for people who are not specialists in e-commerce, auctions, or programmed-trading protocols. It should be relatively platform independent because we cannot afford to constrain a diverse user community to any one platform. Where possible, we should use existing standards in the interface and protocol specifications.

A simple design serves both the user-friendliness and correctness goals. The services provided by the AuctionBot -- submitting auctions, placing bids, receiving price quotes, notifying clients of clearings -- are fundamentally simple. Our design drew inspiration from a number of sources, notably Mike Gancarz's The UNIX Philosophy (Digital Equipment Corp., 1996) and a trove of AT&T technical reports (available at ftp://plan9. bell-labs.com/ cm/cs/cstr/index.html and ftp://plan9.bell-labs.com/plan9/doc). The use of ASCII text strings to transmit data between client and server was inspired by statements such as "...in Plan 9, devices are controlled by textual messages, free of byte order problems, with clear semantics for reading and writing. It is common to configure or debug devices using shell scripts" (ftp://plan9.bell-labs.com/plan9/ doc/9.html). The overhead associated with string conversions is far outweighed by the ease of composing and debugging human-readable messages.

Because we deal only with the price-negotiation phase of electronic commerce and not the monetary transaction phase, villains have less incentive to attack a system that uses the AuctionBot. Security is explicitly not a design criteria. All communication between client and server occurs in plaintext. The server authenticates clients, but not in a secure way. The mechanism is sufficient to prevent inadvertent errors, but it offers little protection against determined attacks by a resourceful adversary. At some point, we may enable secure client/server communication by using a commercially available technology, but this is not a high priority.

Backward compatibility is another issue addressed by our design. Since strings can be thought of as associative arrays, it's easy to add new features (new key-value pairs) without breaking existing code or client-server interactions.

All messages are encoded in the common URL format. We chose this format (see Example 1) because we had working code that parsed URL-based messages, and we didn't want to force users to learn yet another message format.

Implementing the API Client

Traditionally, an API is viewed as a set of data structures and functions whose implementation reside on a local machine in static or shared libraries. Programmers access supported services by linking to the API library (at either compile or run time) and calling its functions through a well-defined interface. In our model, the API functions reside on a server (not locally), and are therefore not linked to the client code. Interfaces to the functions are well-defined messages encoded as strings that are sent to the server through a specific port and invoke API functions that run on the server. The server functions return string-based messages through a socket to the API client informing it of the result of the request.

This is similar in spirit to Remote Procedure Calls (RPC). The main difference between RPCs and our method is we carefully specify a platform-independent communication format so nobody needs to use any particular RPC library.

We achieve platform independence by emphasizing the format in which messages travel from client to server, rather than the code libraries that clients use to interact with the server. The C++ code we provide simply helps client-agent designers get started, but the interface is a set of communication conventions, rather than a library of functions. (Some would say we're providing a protocol rather than an API and that the C++ code we provide merely helps people use the protocol.)

The C++ API client (see Figure 1) implementation consists of network services and support services. Network service functions are the heart of the API client. They are used to establish a connection with the AuctionBot server and to send and receive data to and from the Auction-Bot server. API support services consist of classes for encoding and decoding API strings. The support layer provides support services and is largely used to formalize the handling of API strings. In fact, a basic API client can consist of only the network services with very little user code.

Network and Support Services

Network services are composed of SetupConnection, WriteAPIString, and ReadAPIString. In Example 2(a), SetupConnection sets up a TCP socket connection to the server. The functions WriteAPIString and ReadAPIString perform as their names suggest. In Example 2(b), WriteAPIString writes an API string to the server over the socket, while ReadAPIString in Example 2(c) reads an API string from the server over the socket.

Support classes are included in the C++ implementation to make handling API strings manageable. APIStringData is used to encode a C string. The class is passed a NULL-terminated string in its constructor and stores the string in an internal representation. Access methods are used to retrieve the values for each corresponding label; see Example 3(a).

The APIStringMsg class is used to format API strings. The AddOpType method adds the operation keyword to the string. AddTerm methods add terms to the string; see Example 2(b).

API Services

Table 1 lists the services supported by the current API implementation. The service set is rich enough to let you implement many software agents. The API has been used to implement agents that simulate the problem of allocating excess production time in a factory by allocating scarce resources among a number of competing agents in a dynamic market environment (see http://auction.eecs.umich.edu/demos/factory.html).

We used the API to build a Bidder class that encapsulates basic bidding functions, thus freeing you from the need to implement your own bid housekeeping code. You could even imagine building an auction web site consisting of a web server, HTML pages, and CGI scripts that use the API to request services from the AuctionBot server.

Examples

Listing One is a basic API client that shows some of the features of the API. The client 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 echoes the string sent from the server. In automated mode, the user passes the program a filename from the command line containing a series of API string messages. The client program reads each message, sends it to the server and echoes the return string.

This example lets users explore API features, but does not perform any useful or interesting task normally associated with an API client. Examples of useful software agents are available at http://auction.eecs.umich.edu/about.html.

Conclusion

The protocol and implementation for this network API is based on encoded strings that are passed over a TCP socket between a client and server. The string-based approach offers advantages over more traditional library-based specifications (RPC) in that it allows extendibility, simplicity, and for platform and language independence. This design lets you easily implement the API in your favorite language and platform.

DDJ

Listing One

/*------------------------------------------------------------------
  Program that connects to the server, sends strings to the 
  server, and echos the server response.
  Copyright (c) 1997-98 The Regents of the University of Michigan.
  ------------------------------------------------------------------*/
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <string.h>
#include <signal.h>
#include <time.h>


</p>
#include <sys/types.h>
#include <sys/errno.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include <netdb.h>
#include <assert.h>


</p>
#include "String.H"
#include "Sockets.H"
#include "Utils.H"
#include "APIStringData.H"
#include "APIStringMsg.H"


</p>
int
main(int argc, char *argv[])
{
  int   port = 50001;
  char *servname = (char *)"auction.eecs.umich.edu";
  int  err = 0, sd = 0, nBytes = 0;
  FILE *fp;
  
  if ((err = SetupConnection(servname, port, sd)) < 0)
  {
    (void)printf("error on SetupConnection()\n");
    exit(EXIT_FAILURE); 
  }
  (void)printf("connected to address: %s\n", servname);
  (void)printf("port:                 %d\n", port);
  char s[MAX_API_STRING_LEN + 1];
  char recvbuf[MAX_API_STRING_LEN + 1];


</p>
  if (argc == 2)
  {
    fp = fopen(argv[1], "r");
    if (fp == NULL)
    {
      printf("error opening input file\n");
      return 0;
    }
    int cnt = 0;
    while (!feof(fp))
    {
      s[0] = 0;
      recvbuf[0] = 0;
      
      (void)fgets(s, MAX_API_STRING_LEN, fp);
      if (strlen(s) <= 0)
        break;
      if (s[0] == '#')
        continue;
      (void)printf("-- (%d)\n%s", cnt++, s);
      nBytes = WriteAPIString(sd, (char *)s, strlen(s));
      if (nBytes == 0)
      {        
        (void)fprintf(stderr, "example: WriteAPIString returned 
                                              0 bytes, calling exit(0)\n");
        exit(EXIT_FAILURE); 
      }
      nBytes = ReadAPIString(sd, recvbuf, MAX_API_STRING_LEN);
      if (nBytes == 0)
      { 
        (void)fprintf(stderr, "example: ReadAPIString returned 0 bytes, 
                                                       calling exit(0)\n");
        exit(EXIT_FAILURE); 
      }
      (void)printf("%s\n", recvbuf);
    }
    fclose(fp);
  }
  else
  {
    (void)printf("type API commands to send to the server\n");
    while (1)
    {
      s[0] = 0;
      recvbuf[0] = 0;
      
      (void)printf(": ");
      (void)fgets(s, MAX_API_STRING_LEN, stdin);


</p>
      nBytes = WriteAPIString(sd, (char *)s, strlen(s));
      if (nBytes == 0)
      {        
        (void)printf("example: WriteAPIString returned 0 bytes, 
                                                   calling _exit(0)\n");
        exit(EXIT_FAILURE); 
      }
      nBytes = ReadAPIString(sd, recvbuf, MAX_API_STRING_LEN);
      if (nBytes == 0)
      { 
        (void)printf("example: ReadAPIString returned 0 bytes, 
                                                    calling _exit(0)\n");
        exit(EXIT_FAILURE); 
      }
      (void)printf("%s\n", recvbuf);
    }
  }
  return 0;
}

Back to Article