From Globus

GridShib Software Interface Guidelines

For the purposes of discussion, we make the following definition:

Definition A minor development cycle is a set of software releases having version numbers of the form 0.N.x where N is fixed and x is arbitrary.

For example, GridShib SAML Tools v0.1.0 through v0.1.4 is a complete minor development cycle, referred to as the GS-ST v0.1.x development cycle.

General Guidelines

The term interface refers to a web user interface, an application programming interface, or a command-line interface.

• A new element of an interface may be added at any time.
• An existing element of an interface may be deprecated at any time.
• An existing element of an interface may only be changed or removed at the beginning of a minor development cycle (0.N.0).
• The lifetime of an interface element is at least one complete minor development cycle (unless otherwise mentioned below).

The above guidelines apply to an exposed interface only, that is, an interface designed specifically for use by end users. An interface that is not exposed is subject to change at any time.

Web User Interfaces

A web user interface (UI) is necessarily exposed. The elements of a web UI include URLs, HTTP request methods (GET or POST), HTTP parameters, and of course the HTTP response.

Command-line Interfaces

A command-line interface (CLI) is likewise necessarily exposed. The elements of a CLI include the name of a command-line script, the options and arguments that make up the syntax of the command line, and the expected output of the script.

Typically, the options associated with a GridShib CLI follow the GNU/POSIX style, that is, each command-line option has a short form (-a) and a long form (--aLongOption). When wrapping a CLI, it is recommended that the long form of command-line options be used, since they are more stable than the short form.

• A short command-line option may have a lifetime shorter than one complete minor development cycle.

Application Programming Interfaces

An Application Programming Interface (API) may or may not be exposed. Exposed APIs will be clearly identified. This note applies to exposed APIs only.

The specific elements of an API depend on the type of language used to implement that API. For example, the elements of an object-oriented API include class names, class member names (fields and methods), method signatures, and the expected output or behavior of methods.