External Interface Specification

Definition

External Interface Specification (EIS)

the requirements work product produced during system or application development that formally specifies the interfaces to all external systems and applications

Objectives

The typical objectives of an external interface specification are to:

• Help establish a consensus among project stakeholders concerning the required system:
  • Data interfaces and protocols.
  • Hardware interfaces and protocols.
  • Software interfaces and protocols.
• Baseline these requirments for validation and acceptance.
• Be a basis for cost and schedule estimates.
• Be a basis for future extensions and enhancements.

Benefits

The typical benefits of an external interface specification are:

• Decrease the time required to integrate the application with existing applications and hardware.
• Increase the quality of the integration between the application and existing non-human externals.

Contents

The typical contents of an external interface specification are:

• Data Interface Specifications (for each data interface):
  • Name of the Data Interface
  • Definition of the Data Interface
  • Interface Objectives (semantics)
  • Data External Location
    (e.g., external File, external database, external software component, external hardware component, external network)
  • Data Flow Direction (e.g., input, output, input/output)
  • Data Types:
    • Name and Definition
    • Encoding (e.g., ASCII, UNICODE, XML, HTML)
    • Units (e.g., Dollars, Meters)
    • Granularity
    • Valid Range
      (and what to do if out-of-range value received)
    • Validity of Null Value
    • Default or Initial Value (if any)
    • Invariants (if any)
    • State behavior
      (if any including what to do if data is received when in the wrong state)
    • Exception handling
    • Correctness:
      • Accuracy
      • Precision
      • Timeliness/Obsolescence
        (will data become obsolete after a specific time and what should be done with obsolete data?)
  • Performance:
    • Periodicity (i.e., periodic or aperiodic)
    • Minimum arrival rate (by state)
    • Average arrival rate (by state)
    • Maximum arrival rate (by state)
    • Maximum time before first input/output
      (including what to do if data is not received within maximum time before expected first input)
  • Communication Protocol (e.g., TCP/IP)
• Hardware Interface Specifications (for each hardware interface):
  • Overview:
    • Definition of the Hardware Interface
    • Interface Objectives (semantics)
    • Interface Type (e.g., cable, optical fiber, physical device)
    • External Hardware Component or Device
  • Connection:
    • Physical Media
    • Physical Configuration (size, shape)
    • Hardware Interface Standard
    • Pin Configuration and Number
    • Voltage, Frequency, and Current
    • Grounding
  • Data/Control Flow:
    • Data Rate and Robustness
    • Input Data Name, Type, and Description
    • Output Data Name, Type, and Description
    • Control Signal Name, Type, and Description
• Software Interface Specifications:
  • Interface Packages
    For each package of logically related interfaces:
    • Name
    • Definition
    • Type (Provided or Required)
    • Semantics:
      • Purpose
      • Invariants
      • State Model
    • Interface:
      For each interface in the package of interfaces:
      • Name
      • Definition
      • Semantics:
        • Operation Preconditions
        • Operation Postconditions
        • Concurrency Semantics
      • Syntax:
        • 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)
      • Quality:
        • Availability
        • Reliability
        • Performance
  • Conclusion
  • Appendices:
    • Major Issues
    • TBDs
    • Assumptions

  Stakeholders

  The typical stakeholders of an External Interface Specification are:

  • Producer:
    • Requirements Team
  • Evaluator:
    • Requirements Evaluation Team
  • Approvers:
    • Technical Leader
    • Project Manager
    • Customer Representative
  • Maintainer:
    • Requirements Team
  • Users:
    • Architecture Team, which uses the requirements in the the EAPIS to drive and validate the system, hardware, and software architecture.
    • Integration Team, which uses the EAPIS to generate integration tests.
    • Software Development Team, which uses the EAPIS to code the interfacing software.

  Phases

  A external interface specification is typically produced during the following phases:

  • Business Strategy: Not Applicable
  • Business Optimization: Not Applicable
  • Initiation: Started. During this phase, only the high risk and architecturally significant interface requirements are specified.
  • Construction: Completed
  • Delivery: Maintained
  • Usage: Maintained
  • Retirement: Archived

  Preconditions

  An external interface specification typically can be started if the following preconditions hold:

  • The requirements team is staffed and adequately trained in requirements specification.
  • Domain experts who know the interfaces are available.
  • The system requirements specification has been started.

  Inputs

  The typical inputs to an external interface specification include:

  • Work Products:
    • System Requirements Specification
    • Existing customer documentation
    • Existing external application documentation
  • Stakeholders:
    • Customer organization domain experts
    • Development organization domain experts

  Guidelines

  • Do not produce an External Interface Specification unless the application must interface with an external systems or applications.
  • Where practical, specify open interface standards with the following decreasing order of preference:
    1. International interface standards
    2. De facto interface standards
    3. Proprietary corporate standards
    4. Proprietary program standards
  • Consider including the specification of external interfaces in an additional section of the system requirements specification rather than in a separate document if there are few mandatory external interfaces and these interfaces are simple.
  • Where practical, specify external interfaces by reference to the published standards or existing documentation about individual external applications rather than redundantly repeating the information.
  • Do not use this specification to specify the internal interfaces of components of the application unless use of these components has been required as a design constraint in the system requirements specification.

  Conventions

  An external interface specification is constrained by the following conventions:

  • Content and Format Standard
  • MS Word Template
  • XML DTD
  • Inspection Checklist

  Examples

  • Example External Interface Specification

  ---

  ---

  ---