Understanding the administrative API

The administrative API for WebSphere Partner Gateway allows certain common administrative functions to be carried out without using the Community Console GUI.

Note: The Community Console must be running for API calls to be processed, and the API functionality must have been turned on in the GUI before the calls are made. For more information using the GUI to turn the APIs on, see the WebSphere Partner Gateway Hub Configuration Guide

A method is called by sending an HTTP POST request with an appropriate XML document as the body. This request is directed to a servlet running on the console instance, at the relative URL of /console/bcgpublicapi.

In general, the XML request document includes the following data:

The following eleven methods are supported:

The system processes the request and returns the response (or exception) XML synchronously, that is, on the same HTTP connection. Each method has a corresponding response. Using an API produces the same internal process that using the Community Console does. If a particular operation that is executed in the Community Console generates events, that operation executed in the API generates the same events.

The administrative API section that follows describes these APIs in detail. More detail can be gathered by looking in the $(WBICINSTALLROOT)/publicapi directory at the two provided schemas:

In addition to the actual response, the servlet itself also provides standard HTTP status codes, as specified in Table 2.

Table 2. Servlet status codes
HTTP status code Situation in which this code is returned
500
  • Request XML cannot be parsed.
  • There is an error in processing the request.
  • There is an internal error.
405
  • An HTTP request other than POST has been received. The servlet supports only the POST method.
200
  • The API has been successfully executed.
501
  • An unimplemented request has been received.
  • The administrative API has not been turned on.

Security is provided by the use of SSL and, optionally, Client Authorization. Data, but not the elements of the API itself, can be localized, based on the locale, as long as character encoding is set to UTF-8, which is the standard expected encoding.

Copyright IBM Corp. 2003, 2005