Interface Design and Definition Document Template — A Short Guide for the Best Results

This article will discuss the Interface Design/Definition Document (or IDD) and provide a basic structure that can be used as a template. The sections below represent the main topics an Interface Definition Document (IDD) must address. However, this list is incomplete; an overview section, a reference guide, and a terms and definitions section must also be included. We have covered each of these items in the Solution Design Document article. In summary, an IDD must cover:

• Interface and system overview
• Constraints and limitations
• Transaction processing and design patterns
• The transaction flow
• The message structure and protocols
• The message fields
• Security
• Communications and data transfer

Before we explore the template, we will discuss the Design Structure Matrix (DSM), an essential part of any solution design document.

This series also cover the following topics:

Interface Design and Management

Interface Design and Management — A How-To Guide for System Engineers

Interface Definition Document Template

Interface Design and Definition Document Template — A Short Guide for the Best Results

Large Systems Integration

Systems Integration — Challenges and Solutions to Assembling Large Systems

From Abstract Concepts to Tangible Value: Solution Architecture in Modern IT Systems

2. Design Structure Matrix (DSM)

2.1 Overview

A Design Structure Matrix (DSM), also referred to as a dependency structure matrix, incidence matrix, N2 matrix, interaction matrix, or dependency map, is a simple, square representation of a system design highlighting the interfaces, dependencies, or links between the system subcomponents.

In the example above, we see four components of the system (including the environment it operates in and the end user) and different types of interfaces between them.

• A sensor reads information (such as temperature or pressure) between the environment and Module B and stores it internally in a database via a database abstraction layer like JDBC or Hibernate.
• The operator interacts with the system via a Graphical User Interface (GUI) or a command-line interface (CLI). An operator can also upload data files via a File Interface.
• Modules A and B share data through an internal API.

2.2 Benefits of Having a DSM

A DSM allows you to do the following:

• Identify quickly opportunities to improve the system design, such as combining similar modules or reducing the overall number of interfaces.
• Understand the impact of any change on the system, like adding a new feature or component.
• Ensure that all players’ interfaces have been accounted for.

A DSM can also be created on different system decomposition levels. A high-level DSM would show the connections between major systems, while a low-level DSM would represent a more granular view. However, its size must remain within the cognitive capacity of its users to remain usable.

A high-level Design Structure Matrix naturally belongs in the High-Level Design Document, whereas a low-level DSM would best be included in a Low-Level Solution Design.

While a DSM is crucial in systems integration projects, it is highly recommended in large software development and implementation projects.

3. Interface Definition Document (IDD) Template

3.1 Interface Overview

The interface overview section presents generic details like terms and definitions, change history, current version number, support contact information, intended audience, and external references.

3.2 Assumptions and Limitations

Any assumptions, limitations, or constraints on the systems connected through the interface or the interface itself must be explicitly mentioned. Example are:

• Hardware or software environment — if specific hardware or software is required to process the message or its contents.
• End-user environment — for example, which browser to use for web pages.

3.3 Transaction Processing, Flow, and Design Patterns

The IDD should specify the adopted design pattern and operation mode, which we now describe.

The following design patterns are typically applied when conceptualizing interface operations.

• Producer/Consumer—This design pattern establishes a preferential direction for information exchange. A producer creates and shares information with a consumer. The data flow can go in either direction, depending on whether this sharing occurs via a push or pull mechanism.
• Switching — A switching system treats all interface connections on a somewhat equal footing. A message arrives from a source and is routed to its destination according to specific rules. The routing is usually determined based on the origin and the message’s content.
• Command and control — Under this paradigm, a command is issued from the control system, and a response is typically expected from the executing system. The message direction can be both ways; commands and responses flow from the control system to the executor, while status messages can be pushed from the executor.

Message flow could be either synchronous or asynchronous. In synchronous operation modes, the sender is blocked until a response is received. In asynchronous modes, the sender continues to perform its task while waiting for a response.

Connection initiation, handshakes, keep-alive, and security key exchanges must be described.

3.4 Message Structure and Protocols

The IDD must contain a detailed definition of the message structure used across the interface. A typical message shared across a system interface is made up of the following components:

• Header
• The message header contains information about the message itself, such as its type, origin, creation time, expiry timeframe, authentication token, credential information, and routing information. It might also include metadata about the message content, such as its length, structure, or format. The information in the message header is crucial for the correct routing, interpretation, and processing of the message.
• Body
• The message body contains the payload, typically containing user and application data of some business value. This data is relevant only to the destined application or user and carries essential information required to complete a service or support system functionality. The message body size can be tiny or even zero (for example, for ping or keep-alive messages). Its most common format is JSON or XML, but it could also be fixed-length, field-delimited, Tag-Length-Value strings, or bitmap structured.
• Footer
• The message footer is an optional field. It might contain special characters to delimit a message or data summary (such as the number of records or a sum of amounts) or checksums for integrity checks.

3.5 Message Definitions

Include the below topics in your IDD on message definition:

• Message types and functionality
• What different message types are supported by the interface, and (briefly) what functionalities do they provide? Typically, a message field indicates the message type and allows the application to distinguish between different services at both interface ends.
• Dependencies
• Any dependencies between the messages (sequential, temporal, functional)
• How to recover from errors, exceptions, or mistakes
• An interface implementation must provide methods for recovering from errors caused by incorrect usage, invalid data, or server-side problems.
• Field conditions:
• A message’s fields can be mandatory, optional, or conditional depending on the message type or the presence and value of other fields. This information is generally provided in a table of allowed fields per message type, with the conditions specified on the field level.

3.6 Data Field Definitions

Include the following topics when describing your interface’s data fields (sometimes called data elements).

• Field definition — A field can be uniquely defined by the following attributes:
  • Unique identifier
  • Name
  • Short description
  • Purpose
  • Alpha-numeric
  • Numeric
  • Strings
  • Dates and timestamps
  • A specific pattern (usually specified with regular expressions)
  • Large character or binary objects (CLOB, BLOB)
  • Number ranges
  • Allowed characters
  • List of values (LOV)
  • Date ranges or conditions
  • Whether the field can be null or must have a default value
  • Mandatory, i.e. must be present for the specific message
  • Optional, i.e. at the sender’s discretion
  • Conditional on the presence of other fields or their values

  3.7 Security

  Messages and message contents must be secure, and this can be achieved through the following security mechanisms:

  • Encryption:
  • Encryption can be applied on the message or field level where individual fields contain sensitive information. Encryption can be symmetric (sender and receiver use the same key) or asymmetric (using RSA, where only the public key is used for encryption).
  • Signatures:
  • Signatures can be appended to messages to verify the sender’s authenticity and data integrity. Signatures are created by hashing the message (or a part of it) and encrypting it with a secret key when using asymmetric encryption. Owners of the public key can authenticate the sender by decrypting the signature and comparing the hash obtained with the one recalculated on the received message contents.
  • Passwords and One-Time Passwords (OTP):
  • Passwords and One-Time Passwords (OTPs) authenticate the user. OTPs provide an additional layer of security by constraining password usage to a limited period or usage count. OTPs are randomly generated for every new session or transaction.
  • Tokens:
  • Tokens can be used to authenticate a session or a user instead of usernames and passwords. Tokens typically have an expiry date, after which they must be regenerated.
  Understanding RSA: The Mathematics Behind Secure Encryption

  3.8 Communications and Data Transfer

  In most applications, communication and data transfer are supported by TCP/IP interfaces and do not require special attention. However, there might be instances where specialized hardware or legacy software is involved, and specific constraints on the message lengths, encoding, format, and processing might apply.

  4. Further Reading