For information on how to construct modules that support APIs, see Designing Reusable Modules.a
Determining the Scope of the API
An API consists of a set of public, extensible methods on public classes and a set of public, non-extensible procedures and functions. The API should provide programmatic access to all aspects of the functionality of the module, for example:
The API should include complete documentation for the signature of each API method, procedure, and function. The signatures should not be subject to change.
Validating Arguments and Signalling Errors
Every API procedure must validate its arguments. Validation consists of two parts:
When you signal an error, you should provide a language-appropriate error message, using the GFR localization facility. You access the language via the client object by using the function
gfr-language. See the G2 Foundation Resources User's Guide for details on localization and error signalling.
G2-WINDOW class. If the client is a G2 window, you can use the client argument to access the user mode, language, and other properties of the window. You pass the window or client along the thread of processing so it is available to other API procedures. If you do not include a client as an explicit argument, the API must provide a way to determine the client object. For example, an object might pass another object that is related through a public relation to the client.
By convention, you should pass the client object as the last argument to the API procedure. For example, this G2 system procedure passes the window as an argument to determine on which window the workspace should be scaled:
g2-lift-workspace-to-top
(kb-workspace: class kb-workspace,
window: class G2-window)
start perform-my-action (the item, this window)
For more information on GFR-DEFAULT-WINDOW, see the G2 Foundation Resources User's Guide.
However, when procedures do not maintain atomicity, it is critical that the API procedure perform validation of its arguments immediately after the single processing thread has been interrupted.
allow other processing, wait, and collect data statements, which interrupt the processing thread.
on error statements in both API and private procedures, except for inter-module API calls.
Shadow Public Procedures with Private Procedures
In general, it is a good idea to shadow each API procedure with a similar private procedure whose name begins with an underscore. The API procedure simply validates its arguments and calls the shadow procedure. The shadow procedure performs the actual functionality of the procedure. That way, core procedures do not have to call API functions to access functionality supported by the API.gxl-get-cell-contents is the API function to get the value stored in a cell of a GXL spreadsheet. This procedure signals an error if row or column are out of bounds for the given spreadsheet. Otherwise, it calls the private procedure _gxl-get-cell-contents. The private procedure performs no further validation on the spreadsheet. Other core procedures call _gxl-get-cell-contents because validation is not necessary.
Limit the Use of On Error Statements
Reserve on error statements for the following circumstances only: