API Guidelines

Object-Oriented Programming with Java, Spring 2008

This page contains some of the desirable attributes an API should display. These are the attributes against which the API and API documented are judged.

1. Presentation Guidelines

   1. Purpose

      1. What does this API do? Why advantages gain to people who use it?

      2. How does this API fit in with the other parts of the system in which it's used?

      3. What conditions must be satisfied before this API can be used?

   2. Overall Structure

      An API's overall structure are the large pieces constitute the API. A Java API's large pieces would be packages and classes.

      1. What are the major components of the API?

      2. What is the relation among the API's major components?

   3. Detailed Structure

      Once the major components and their relations have been described, the last unknown is features of major components aren't other major components (the leaves of the major component tree).

      1. What does the feature do?

      2. What are the necessary conditions for the feature to be used successfully?

      3. What are the results of using the feature correctly?

      4. What error conditions or exceptions are invoked if the feature is used incorrectly?

2. Design Guidlines

   1. Completness: the design should allow for the functions described in the documentation.

   2. Consistency: Features similar in use or results should be similar in design.

      1. Necessary consistency violations should be documented and justfied.

This page last modified on 4 April 2008.