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.
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.
An example of a Design Structure Matrix (DSM) includes an operator, a system of two components and an environment in which it operates.
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.
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 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.
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
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:
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.
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.
To provide the best experiences, we use technologies like cookies to store and/or access device information. Consenting to these technologies will allow us to process data such as browsing behavior or unique IDs on this site. Not consenting or withdrawing consent, may adversely affect certain features and functions.
Functional
Always active
The technical storage or access is strictly necessary for the legitimate purpose of enabling the use of a specific service explicitly requested by the subscriber or user, or for the sole purpose of carrying out the transmission of a communication over an electronic communications network.
Preferences
The technical storage or access is necessary for the legitimate purpose of storing preferences that are not requested by the subscriber or user.
Statistics
The technical storage or access that is used exclusively for statistical purposes.The technical storage or access that is used exclusively for anonymous statistical purposes. Without a subpoena, voluntary compliance on the part of your Internet Service Provider, or additional records from a third party, information stored or retrieved for this purpose alone cannot usually be used to identify you.
Marketing
The technical storage or access is required to create user profiles to send advertising, or to track the user on a website or across several websites for similar marketing purposes.
To provide the best experiences, we use technologies like cookies to store and/or access device information. Consenting to these technologies will allow us to process data such as browsing behavior or unique IDs on this site. Not consenting or withdrawing consent, may adversely affect certain features and functions.
Functional
Always active
The technical storage or access is strictly necessary for the legitimate purpose of enabling the use of a specific service explicitly requested by the subscriber or user, or for the sole purpose of carrying out the transmission of a communication over an electronic communications network.
Preferences
The technical storage or access is necessary for the legitimate purpose of storing preferences that are not requested by the subscriber or user.
Statistics
The technical storage or access that is used exclusively for statistical purposes.The technical storage or access that is used exclusively for anonymous statistical purposes. Without a subpoena, voluntary compliance on the part of your Internet Service Provider, or additional records from a third party, information stored or retrieved for this purpose alone cannot usually be used to identify you.
Marketing
The technical storage or access is required to create user profiles to send advertising, or to track the user on a website or across several websites for similar marketing purposes.
