1. Overview
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 dive into the template, we will discuss the Design Structure Matrix or DSM, an essential topic in any solution design document.
The following topics are also covered by this series:
2. Design Structure Matrix (DSM)
2.1 Overview
ADesign Structure Matrix(DSM), also referred to as adependency structure matrix,incidence matrix,N2 matrix,interaction matrix, ordependency 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.
- Between the environment and Module B, a sensor reads information (such as temperature or pressure) 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 into the system 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:
- Quickly identify opportunities to improve the system design by, for example, bringing similar modules together 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 interfaces between all players 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.
The natural place of a high-level Design Structure Matrix is 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
The Interface Design/Definition Document (IDD) template should cover the following aspects.
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 typically 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 on the message itself, such as its type, origin, creation time, expiry timeframe, authentication token, credential information, and routing information. It might also include metadata on the message content, such as its length, structure, or format. The information content of 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 at both ends of the interface to distinguish between different services.
- Dependencies — Any dependencies between the messages (sequential, temporal, functional)
- How to recover from errors, exceptions, or mistakes — An interface implementation must provide methods to recover from errors caused by incorrect usage, invalid data, or server-side problems.
- Field conditions — Fields of a message 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 also called data elements).
- Field definition— A field can be uniquely defined by the following attributes:
- Unique identifier
- Name
- Short description
- Purpose
- Field formats— Familiar field formats include
- Alpha-numeric
- Numeric
- Strings
- Dates and timestamps
- A specific pattern (usually specified with regular expressions)
- Large character or binary objects (CLOB, BLOB)
- Field Validators— For example:
- Number ranges
- Allowed characters
- List of values (LOV)
- Date ranges or conditions
- Whether the field can be null or must have a default value
- Field presence— This attribute is commonly defined on the message level. Fields can be:
- 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:
- Encryptioncan 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, for example, where only the public key is used for encryption).
- Signaturescan 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) are used to 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 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.
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.
