COMP 310

API Design and Evaluation Considerations

    Current Home  Java Resources  Eclipse Resources

Application Programming Interfaces (APIs) are critical parts of any system because they are the "glue" that holds the decoupled modules in system together.   These modules are the "blocks" in a System Block Diagram.   APIs connect modules that are not just semantically separate but may also be physically separate, perhaps as different processes or applications or on different machines separated by thousands of miles.   APIs often need to be language independent because the modules may be implemented in different languages and technologies.

There is no "recipe" for designing or evaluating an API.

An API is a clean, clear expression of a set of behaviors and protocols that enable the realization of the set of use cases that cross the inter-module boundary controlled by the API.

 Some important observations about APIs:

Some high-level characteristics of APIs:



If the API doesn't do its job, it's useless. An API is defined by the use cases that pass through it.   Specifically, an API is defined by the atomic (indivisible) use cases that cross the boundary between two modules in a system block diagram which was derived from the use cases.  See Use Case-driven System Block Diagrams.

The entire API design process must be driven from use cases, i.e. what tasks need to be accomplished across the interface represented by the API.

If an API cannot support a necessary use case, it is not correct.  Conversely, an API's correctness is determined by its ability to support all the necessary use cases.

 Likewise, an API cannot be determined if the atomic use cases crossing the boundary are not clearly articulated,  This means that creating a detailed use case diagram of the system is the crucial first step before attempting to decide on the methods on an API.

The most common mistake in API design is to try to fill the API with methods before the affected use cases have been determined. 



"Selling" an API Proposal

It is one thing to have designed a wonderful API; it is another to convince someone else to support and adopt it. Buy as is always true in any sort of marketing campaign, the key is to put yourself into the shoes of the person you are trying to convince.  Some things to consider:

Actual code is often far less important in selling a proposal than many people think.  Code just gives names and syntax to the actual purposes of the API.    What an API is trying to accomplish and the fundamental means it achieves those objectives is far more important than the code used to represent it.


API Proposal Evaluation

The evaluation of an API is obviously centered about many of the characteristics outlined above but there are other considerations that affect whether or not one will support an API proposal:


© 2017 by Stephen Wong