Interface Specifications

DEFINITION

An interface specification is a statement of what an architect chooses to make known about an element in order for other entities to interact or communicate with it.

An interface is documented with an interface specification. Although an interface constitutes every interaction an element has with its environment, what we choose to disclose about an interfacethat is, what we document in an interface specificationis more limited. Writing down every aspect of every possible interaction is not practical and almost never desirable. Rather, the architect should expose only what users of an element need to know in order to interact with it. Put another way, the architect chooses what information is permissible and appropriate for people to assume about the element and unlikely to change.

The interface specification documents what other developers need to know about an element in order to use it in combination with other elements and provides a statement of other visible properties. Note that a developer might observe element properties that are an artifact of how the element is implemented but that are not in the interface specification. Because these are not in the interface specification, they are subject to change, and developers use these at their own risk.

Documenting an interface is a matter of striking a balance between disclosing too little information and disclosing too much. Disclosing too little information will prevent developers from successfully interacting with the element. Disclosing too much will make future changes to the system more difficult and widespread and makes the interface complicated for people to understand.

Also recognize that different people need to know different kinds of information about the element. The architect may have to provide separate sections in the interface document or multiple interface documents to accommodate different stakeholders of the element.

ADVICE

Guidelines for Writing an Interface Specification

• Focus on how elements interact with their environments, not on how elements are implemented. Restrict the documentation to phenomena that are externally visible.
• Expose only what actors in an element's environment need to know. Including a piece of information in the documentation is an implicit promise to the element's stakeholders that the information is reliable and stable. Once information is exposed, other elements may rely on it, and changes will have a more widespread effect.
• If you don't want people to rely on a piece of information, don't include it in the interface documentation. Make it clear that information that "leaks" through an interface but is not included in its interface documentation can be used only at the peril of the actors that exploit it and of the system as a whole.
• Keep in mind who will be using the interface documents and what types of information they will need. Avoid documenting more than is necessary.
• Be as specific and as precise as you can, remembering that an interface specification that two different parties can interpret differently is likely to cause problems and confusion.

Interface specifications are documented as part of a view. When similar interface information occurs in more than one place, choose one to hold the interface specification and refer to it in the other.

For example, elements in a module view often correspond directly to one or more elements in a C&C view, and the module and C&C elements are likely to have similar, if not identical, interfaces. Documenting them in both places would produce needless duplication. To avoid that, the interface specification in the one view can point to the interface specification in the other view and contain only the information specific to its view.

Another example is that a set of C&C components might all provide instances of the same interface type, except that the resource names are prefixed with the name of the component and two of the components have a couple of extra resources. Document these interfaces by documenting the interface type in one place: either with one of the components or, perhaps, with the corresponding module. Document the deltas with each component.

Similarly, a module may appear in more than one module view: decomposition and uses, for example. Again, choose one view to hold the interface specification and refer to it in the other.

As in all architectural documentation, the amount of information conveyed in an interface specification may vary, depending on the stage of the design process captured by the documentation. If the interface is part of an element that is being developed in the system, the interface might be partially specified early in the design process; for example, module A provides the following services. Later, when the responsibilities of the the elements become stable, the interface specification is more fully elaborated; for example, module A provides method X with signature Y and semantics Z. Remember that an important rule for sound documentation prescribes using a standard organization, such as the one suggested in the next section. A standard organization lets you fill in what you know now and indicate TBD for what you don't yet know, thus providing a to-do list for the remaining work.