COMP 310	API Design and Evaluation Considerations

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:

• Invariant: API's are some of the most invariant parts of a large system.
• Behaviors + Protocols: API's involve not just behaviors but protocols that govern when and how those behaviors are invoked.
• Arise from Use Cases: An API cannot be designed without fully understanding all of use cases that cross the boundary controlled by the API.
• Sub-Parts: An API may be separable into semantically distinct sets of operations.   This will lead to the API consisting of multiple entities such as interfaces that are used to represent each semantically separate set of operations.

Some high-level characteristics of APIs:

• Correctness -- The API must be able to properly support all the operations that need the API.
• Minimal and Complete -- Strive for the minimum number of methods that for a complete set, enabling all required operations to be performed.
• Orthogonality --  All methods should be maximally independent of each other and not perform operations that are also partially performed by other methods.
• Implementation Independent --  The user of a method or object should not be concerned with how it is implemented.    
• Flexibility -- All possible operations must be able to be accomplished with the defined set of operations and objects without the need for special cases.
• Extensibility -- The addition of new operations and/or capabilities should not require major reconfiguration of the system, preferably no changes at all. 
• Robustness --  The system should be designed to gracefully handle user or other errors that may occur.
• Security --  The system should be gracefully disallow deliberate attempts to circumvent proper operation.

Correctness

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:

• How can you express your ideas such that they make sense and are compelling to your audience?   In the end, any arguments must make sense from their viewpoint, not yours.
• Are you clearly addressing the important issues of your audience?  For instance, if they have a particular use case that is critical for what they want to accomplish, can you convince them that your proposed API is able to handle that use case?
• Are you able to clearly describe how the API accomplishes its use cases in a simple, straight forward manner?
• Are you able to prove that any unhandled use cases are inconsequential to the system, at least for a reasonable operational period?   
• Are you able to make convincing arguments that the API will be able to evolve to handle tomorrow's needs without requiring massive system reconstructions?

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:

• Correctness:  Can all the use cases that need the API actually accomplish their tasks within the capabilities of the API?  
  • Some tasks may require a combination of multiple API method calls.
  • Note that this is not the same the "usability" trait described below.
• Clarity:  How clear was the proposal in making its case for the merits of the proposed API?
• Completeness: How complete is the proposal?
  • Technically, does the proposed API handle all the possible use cases that cross its boundary?  
  • Do proposal materials, both written and oral, fully discuss all those use cases? 
• Usability:  How easy is it for a "regular" person to use the proposed API?
  • Flexibility:  Does the API allow an implementer to have freedom in what they can do and how they implement the API's functionality?
  • Simplicity:  Is the API easy to understand and implement?
  • Ease-of-use: Is the API easy to use?
• Persuasiveness: Does the proposal put forth clear and compelling rationales backed by solid technical details that form a cohesive, persuasive argument for the merits of the proposed API?

© 2017 by Stephen Wong