External API Requirements

Definition

An external API requirement is a requirement that specify a mandatory aspect of an application programmer interface (API) of the thing being specified.

Objectives

The typical objectives of external API requirement are to specify:

• A mandatory application programmer interface (API).
• A mandatory protocol.

Types

The following are typical types of external API requirements:

• Data API Specifications including required:
  • Name and Definition
  • Encoding (e.g., ASCII, UNICODE, XML, HTML)
  • Units (e.g., Dollars, Meters)
  • Valid Range
  • Validity of Null Value
  • Default Value (if any)
  • Security Level
  • Invariants (if any)
• Hardware API Specifications including required:
  • External Hardware Component:
    • Interface Name and Definition
    • Interface Objectives (semantics)
    • Interface Specification (syntax)
    • Interface Protocol (behavior)
• Software API Specification including required:
  • Interface Name and Definition
  • Interface Purpose (semantics)
  • External Software Location (e.g., hardware component, software component)
  • Security Level
  • Interprocess (i.e., inter-address space) communications (e.g., kernel calls) mechanisms (if applicable)
  • Package Interface:
    • Package Name and Definition
    • Package Objectives (semantics)
    • Visible Classes/Objects
  • Class Interface:
    • Class Name and Definition
    • Class Invariants
    • Visible Operations
    • Visible Attributes (if any)
  • Operation Interface:
    • Operation Name and Definition
    • Operation Preconditions
    • Operation Postconditions
    • Parameters (e.g., data types, valid ranges, validity of null values, default values, data flow direction of in/out/inout)
    • Return Value (e.g., data type, valid range, validity of null value, default value)
    • Exceptions Thrown
  • Communication Protocol (e.g., Remote Procedure Call, Remote Method Invocation, CORBA, DCOM)

Guidelines

The following guidelines have been found to be useful when producing external API requirements:

• Do not confuse external API requirements with other types of requirements (e.g., data requirements).
• An external API requirement is typically specified in exernal API specification.