5.1 Inter-System Interface Requirement Pattern

5.1 Inter-System Interface Requirement Pattern

Basic Details

Related patterns:	Inter-system interaction, throughput, availability, extendability, comply-with-standard, documentation, technology
Anticipated frequency:	Four or fewer requirements in a small-to-medium system; possibly a dozen or more requirements in a complex system
Pattern classifications:	None

Applicability

Use the inter-system interface requirement pattern to specify basic details for an interface between the system being specified and any external system or component with which it needs to interact.

Do not use the inter-system interface requirement pattern for user interfaces (though you can treat interactions to user devices and user interface infrastructures as inter-system interfaces if they behave in a similar way to an external system). Also, do not use this pattern for internal interactions between different parts of the system, unless an external system might participate in those interactions at some time in the future (that is, if it might become an external interface).

Discussion

Getting one system to cooperate with another can be a time-consuming and unpredictable undertaking. Developers might have little idea how hard it will be to implement a particular interface until they get their hands dirty. If we're using an interface defined by someone else, it might not do exactly what we want or might not work as we expected; if we're designing the interface ourselves, we're dependent on the owners of the other system to implement it properly. As a result, it's important that we treat inter-system interfaces with respect and that we don't under-estimate their complexity: give them plenty of visibility, pin them down as early as possible, and allocate them sufficient resources. Often these don't happen, in many cases because the requirements specification glossed over the interfaces-or even failed to recognize some altogether. As a result, a system's interfaces might be weak links.

This requirement pattern cares neither about the nature of the interface nor whether the external system is local or remote. It uses the general term "interaction" to describe an activity across the interface (which usually means an exchange of information).

Every requirements specification should contain a system context diagram, and it should be near the beginning. (See the "Scope" section in Chapter 2, "The Contents of a Requirements Specification.") This is where interfaces make their first appearance, so take the opportunity to give them star billing. On the context diagram, show all external systems (and other components) with which our system needs to interact, and label every connection to them explicitly with an interface ID. Figure 5-2 shows a sample context diagram with features related to interfaces indicated.

Figure 5-2: Sample system context diagram

There are several points to observe. First, each interface is identified by its unique interface ID (using the convention described in the "Content" section later in this pattern). Next, each interface ID is either inside or outside the boundary line of the system's scope. Every interface must eventually be either wholly inside or wholly outside. If ownership of the interface has yet to be determined, the interface can be shown straddling the scope boundary; highlight this unresolved issue with a large question mark. Finally, when there are multiple similar systems to which to interface (such as the multiple credit card clearing houses in Figure 5-2), each must be treated separately, because they are all different. The connection to each is a separate interface. Don't lump an indeterminate number together. See the "Interface Adapters" section that follows for a discussion on how to handle interfacing to multiple systems for the same purpose. If we need to be able to handle multiple instances of a particular type of interface, then there are various extra factors to consider-such as deciding which to use and when. These factors are discussed in the extendability requirement pattern in Chapter 10, "Flexibility Requirement Patterns."

Interface Adapters

We're building a beautiful new system. We want to keep at arm's length anything messy that would spoil its pristine elegance-such as having an indeterminate number of interfaces of some kind (like the credit card clearing houses in Figure 5-2). We can avoid our core system dealing with lots of external interfaces for the same purpose by interposing a single interface of our own choosing and plugging in a piece of software, called an adapter, to do whatever's necessary to convert this into what a particular external interface expects. This is shown conceptually in the following diagram:

The core system deals only with a single interface for this purpose (I_A), and the adapter deals with the external component's interface (I_E). We can build as many different adapters as we need to. This is especially beneficial when building a product because third parties (including our customers) can build their own extra adapters, and we don't have to modify the core system every time. We can, on a case-by-case basis, place each individual adapter either inside or outside the scope of our system.

If there's a widely-accepted standard for a particular interface, we could adopt and use that interface-yet we might still encounter external systems that don't use it. In this situation, we could build adapters for the one-off cases but would need no adapter for the standard interface. Before adopting an externally-specified interface definition and asking third parties to use it, first check whether you're allowed to; it might be proprietary and confidential or carry licensing restrictions.

Adapters are ordinarily a design matter, but it becomes very beneficial to introduce them in the requirements whenever we want the freedom to place interfaces of a particular type in scope and leave some out of scope. See the extendability requirement pattern in Chapter 10 for discussion of additional factors.

Between two systems, there might be more than one interface (for example, a custom messaging protocol for transactions and email for sending monthly reports). Treat each different communication medium as a separate interface, because they'll have to be built and tested separately and will function independently.

Interfaces that are wholly within the system's scope (and don't involve any component outside that scope) normally don't need to be dealt with in requirements. One exception is if development is to be split between multiple teams (especially if one team is not in-house or if the teams are physically remote from each other). Requirements can only deal with this if it's known at requirements time and if the system is clearly segregated-in effect, if we're specifying a "federation" of systems. Another exception is when we envisage part of our system being spun off in the future and used by other systems (as for the Access Controller in Figure 5-2).

If interfacing to a third-party system, it is reasonable to define requirements that its supplier must satisfy: documentation, performance, availability of a test system, test accounts and so on-everything we need to be able to build and test our end of the interface. Bear in mind that third parties might have very different standards and abilities from those of your organization; they might be capable of meeting far higher professional standards than you need-and might charge you accordingly if you use them. At the other end of the scale, they might have poorer practices and skills than your own developers.

The Ups and Downs of Interface Ownership

Sometimes we'll use an existing interface; sometimes we must define an interface ourselves; occasionally we can choose whether to take responsibility or leave it to whoever owns the system at the other end. How do we choose? There are arguments both ways. It's useful to understand them even if the decision is forced on you.

The great benefit of defining an interface yourself is control: you can make sure it does what you want, how you want, and you know it's not going to change unless you want it to. You can do it your way. The downside is that you have to do all the hard work of defining it-as well as explaining it to everyone else who will implement it, which means documenting it and possibly supplying them with your interface software.

Using an interface defined by someone else means living with what they provide: it might be awkward to use, badly documented, involve technology that you don't use or with which your developers aren't familiar. A widely-used interface might be overly complex for your needs-perhaps designed by committee. The interface might change, presenting you with ongoing upgrade work-possibly to tight time deadlines outside your control. The interface's owner might be unresponsive to changes that you need-if they're prepared to make changes for you at all-and then charge you for the privilege. On balance, doing the work yourself is often a price worth paying to avoid these risks-but sometimes it's too expensive a price.

Overall, the most successful outcome is likely to be achieved if the interface is owned by whoever has the greatest vested interest in its success.

Content

An inter-system interface requirement contains the following:

1. Interface name Give each interface a concise meaningful name-something convenient for people to use in discussion.

2. Interface ID Give each interface an identifier that is unique within the scope of this system so it can be easily and unambiguously referred to. One convention that works well is using "i" (lowercase to distinguish it from the numeral 1) followed by a sequential number. Where multiple interfaces serve the same purpose, use a two-part number, where the first identifies the purpose and the second distinguishes the interfaces (such as i1.1, i1.2, …).

3. The system at each end It's possible for the same interface to appear more than once on the system context diagram. But show the same interface ID only if two interfaces serve the same purpose. In this case, explain the roles the two systems play in the interface, or cite each pair of systems explicitly.

   Also identify which of the two systems can initiate an interaction; both might be able to.

4. Interface purpose(s) Describe each distinct purpose-all of them.

5. Interface owner Which organization is responsible for the definition of the interface? It could be designed cooperatively, but one organization should be the ultimate arbiter (to avoid misunderstandings and to settle arguments definitively). See the previous section titled "The Ups and Downs of Interface Ownership" for the relative merits of owning or not owning the interface's definition.

6. Standard defining the interface (if any) Also state its version explicitly. Refer to the comply-with-standard requirement pattern later in this chapter for guidance on what else to say about the standard: the location of the standard, in particular.

7. Technology to be used for the interface (if relevant) If particular technology must be used for the interface, describe it. Otherwise omit this item: don't make technology choices. See the technology requirement pattern later in this chapter for further details on what to say.

A single requirement like this usually isn't sufficient to fully specify the interface (although it might refer to a standard that does). Its main role is to give the interface "official recognition," so it's treated with the respect it deserves.

Template(s)

Open table as spreadsheet

Summary

Definition

«Interface name» interface («Interface ID»)

There shall be a clearly defined interface (called «Interface ID») between «Component 1» and «Component 2». Purposes: «Interface purpose 1». … Interactions across this interface can be initiated by «Initiating components». This interface's definition is the responsibility of and owned by «Interface owner organization». [This interface shall comply with version «Standard version» of the «Standard name», whose definition can be found at «Standard location».] [«Technology statement».]

Example(s)

Open table as spreadsheet

Summary	Definition
Payment clearing interface (i4)	There shall be a clearly defined interface (called i4) between the system and payment clearing houses. It is invoked by the system only. Its purpose is to allow a customer to pay for an order. Ownership of this interface is within the scope of the system.
Alarm monitor interface (i5)	There shall be a clearly defined interface (called i5) between the system and an external alarm monitor. It is invoked by the system only. Ownership of this interface is within the scope of the system. Its purpose is to notify appropriate personnel of any event that is relevant to them (which usually means only serious problems).
Accounting system interface (i6)	There shall be a clearly defined interface (called i6) to an external accounting system. It is invoked by the system only. Ownership of this interface is within the scope of the system. Its purpose is to pass accounting entries (or information from which accounting entries can be generated) resulting from all activities in the system that have financial consequences.
Certification authority interface (i7)	There shall be a clearly defined interface (called i7) between the system and a certification authority (CA). It is invoked by the system only. Its purpose is to verify a digital certificate presented by a customer. It shall be possible to support multiple CAs (for example, eSign, Baltimore). Each CA shall prescribe its own interface (though at least some are expected to use the PKCS #10 standard-see http://www.rsasecurity.com/rsalabs/pkcs/pkcs-10 for details).

Extra Requirements

An inter-system interface requirement might be followed by several extra requirements, although sometimes none are needed. Run through the following list of topics to see which you need to address:

1. Individual types of interaction The main interface requirement states the purpose(s) of the interface, but you might wish to say more about the main types of interactions. There might also be secondary interactions that deserve a mention; apply the inter-system interaction requirement pattern for each one.

2. Throughput How much traffic must the interface be able to handle? Follow the throughput requirement pattern.

3. Scalability How well must the interface cope with increases in throughput? Follow the scalability requirement pattern.

4. Extendability Do you need to be able to slot in extra interfaces of this type? This has been referred to several times in this requirement pattern. If you do, write suitable requirements as described in the extendability requirement pattern.

   Also, do you need to be able to switch the interface on and off? And what configuration parameters does it need? The extendability requirement pattern tackles these questions, too.

5. Resilience and availability Do we need to detect missing or duplicated traffic? How well and how quickly must the interface recover from a failure? During what hours does it need to be running?

6. Traffic verification and recording Must we be able to tell exactly what was sent and received? To prove we sent or received something? Or that the other system acknowledged receipt of something?

7. Upgrading What happens when the interface changes? Must we be able to support old and new versions simultaneously?

8. Security An interface is a door into (and out of) our system. To what lengths must we go to verify access and to stop intruders? Are we worried about strangers getting their hands on the information that is passing along the interface?

9. Documentation and third-party interface development If you're defining the interface, how are you going to tell the developers of the system(s) at the other end what they need to do? How will they test their part?

The first four topics are covered in their own requirement patterns; each of the last five is discussed in its own subsection that follows. This list looks daunting, but it isn't as tough as it appears. The requirements for a typical interface need worry about few of these topics; most can be left to the development team to sort out.

The extra requirements are most readable if they immediately follow the main requirement for the interface to which they relate. But it can be beneficial to group all the main inter-system interface requirements together and then have the extra requirements later on (perhaps even in a later section of the requirements specification). This has the advantage of giving a clear overview of all the interfaces in one go without getting bogged down in the details.

Resilience and Availability Requirements

Most interfaces involve some sort of communications mechanism, which occasionally have traffic hiccups. Resilience in an interface means being able to identify anomalies and deal with them: to spot when messages are missed and ask for them to be re-sent and to spot duplicate copies of messages. Some message protocols and other types of interfaces take care of these things for us, but if you want to play it safe, you can write a requirement demanding this kind of resilience, which acts as an instruction to the developers to take care of it. The requirement needn't worry about how it's achieved. If the developer knows that the underlying messaging protocol handles resilience already, there's nothing more they need to do.

Here's an example interface resilience requirement:

Open table as spreadsheet

Summary	Definition
Warehouse interface fixes omissions	The interface between the system and the warehouse (i2) shall detect missing messages and arrange for them to be re-sent and shall detect and ignore duplicates of messages already received.

Requirements for the availability of an interface-both its normal availability window and downtime targets-can be written in the same way as for the availability of a system as a whole. Follow the availability requirement pattern but limit your focus to the interface only. Clearly identify the interface to which each resulting requirement relates.

Traffic Verification and Recording Requirements

This is a mixed bag of features that collectively act as a sort of passport control for the interface. They come into play once messages have safely completed their journey (or before they set out). Consider whether you need to do any of the following:

1. Verify the identity of the sender This could mean the identity of the other system, the organization to which it belongs, an individual (such as the author of an email)-or all these things.

2. Record messages (logging) Think about incoming and outgoing traffic separately: do we need to know what we sent? Do we need to know what we received? Do we need to record all types of traffic, or just some? The volumes might be large if we record everything, making it awkward to store and harder to find an individual message-even if only marginally so, in this high-capacity age. Refer to the chronicle requirement pattern in Chapter 7, "Data Entity Requirement Patterns," for information on what to say.

3. Record acknowledgment of receipt This is a special case of recording a message for the special purpose of being able to prove that the other party received the information we sent them. It can be used, for example, along with other steps, to prove that both they and we possessed particular information (or a document or another resource) at a particular time.

The motivation for such steps is sometimes legal: to provide proof that another party requested, saw, possessed, or did something. This being so, you need to understand the level of proof needed in your country (or in all the countries in which your system will operate). You might be in for some nasty surprises. You might, for example, need to record messages on a write-once read-many (WORM) medium, to prove that it hasn't subsequently been tampered with.

Here is an example requirement for each of the three topics discussed:

Open table as spreadsheet

Summary	Definition
Verify identity of affiliate	Whenever an affiliate establishes a remote connect to the system, their identity shall be verified. A secure mechanism shall be used for this verification such that interception of communications traffic between the affiliate and the system does not disclose any information that could help a third party impersonate the affiliate.
Record all emails	Every email sent by and every email received by the system shall be stored persistently.
Record all acknowledgments received	The system shall record every acknowledgment received from the warehouse system for dispatch requests sent to it. Each acknowledgment shall be regarded as proof that the warehouse system has accepted responsibility for fulfilling that dispatch request.

Upgrade Requirements

An interface can be tough enough merely to get going in the first place, so why on earth would you want to change it? Well, the functionality might need to change, or a new version of an interface standard might come along. There are two strategies for switching over to a new version of an interface:

• Strategy 1: Change the software at both ends of the interface at the same time. This is the easiest option to implement, but it demands careful coordination of the upgrading of the systems at both ends. It's often impractical even if only two systems are involved, and it becomes steadily more impractical as the number of systems grows.

• Strategy 2: Have each participating system accommodate both the old and new versions. This is necessary until every system has stopped using the old version, and then it can be dropped. If it takes a long time to switch all systems (or, indeed, if some never switch), then more than two versions must be supported at once. The complications don't end there: to be smart, each system needs to be able to tell which version(s) are supported by each other system it talks to. This involves storing this information and/or including an interaction that allows a system to ask another system what it supports. Life is easier if interactions of this sort are present in the first version of the interface.

These sound like design questions, but they must be addressed in the requirements because they affect external systems. If an interface development guide is written, it should say which strategy is to be used-although it is conceivable for one version to use a different strategy than the previous version used.

For an interface not owned by us, the requirements should say the extent to which we are committed to keeping our system compatible with future versions of the interface. If nothing is said, readers can reasonably assume the system merely has to work with the stated version (or whichever is the current version when the system is built). Refer to the comply-with-standard requirement later in this chapter for further discussion on this subject.

Here are example requirements for strategies and situations discussed in the preceding section:

Open table as spreadsheet

Summary	Definition
Warehouse interface simultaneous upgrade	Any change to the interface between the system and the warehouse system shall be installed simultaneously by both systems. The intent of this requirement is to simplify the interface and its implementation by eliminating the need to support more than one version of it at a time.
Multiple versions of affiliate interface	The system shall support multiple versions of the affiliate interface concurrently. All versions of the interface released within three years shall be supported. The intent of this requirement is to avoid forcing all affiliates to upgrade whenever a new version is released, and to have to do so at the same time.
Credit reference interface upgrade	Whenever the credit reference agency releases a new version of the interface to its credit reference service, the system shall be amended to use the new version. Amendments of this nature shall be installed within three months of the new version being released.

Security Requirements

Whenever the subject of security arises, it's likely to be complex and tricky. This little section has no pretensions to being systematic or comprehensive; it merely raises a few issues for you to consider. Let's divide the problem into two parts: the communication medium used by the interface and the traffic that travels along it.

The communication medium used by the interface needs to be protected to prevent intruders from using it to gain general access to our system (hacking in). Requirements can easily address this in solution-independent terms. (No mention of firewalls or virtual private networks or such here!) Unfortunately, it's difficult to decide or express how much protection we need: it can't be quantified. Here's an example requirement of this kind:

Open table as spreadsheet

Summary	Definition
Warehouse interface intrusion protection	The communications medium used by the warehouse interface (i2) shall be protected to prevent an intruder from using it to gain unauthorized access to the system.

As for the traffic, there are various kinds of attacks we could be subjected to, but they boil down to the active and the passive. In an active attack, an attacker modifies the traffic: creates bogus messages, modifies genuine messages, or prevents the transmission of traffic. A passive attacker simply listens to our traffic to get hold of sensitive information. You need to write a requirement to protect against each type of attack you're worried about. Again, specify what you aim to achieve: avoid specifying in terms of solutions-though you can mention an approach if it's obvious. (Common approaches include encryption to prevent the reading of information, hash codes to detect tampering, and digital signatures to verify who sent messages.) Here are a couple of example requirements:

Open table as spreadsheet

Summary	Definition
Warehouse interface bogus traffic detection	It shall be possible to detect bogus traffic on the warehouse interface (i2). Bogus traffic is any message that was not generated by one of the components legitimately participating in the interface, or any message generated erroneously by a legitimate component.
Warehouse interface traffic not readable	It shall not be possible for an intruder who can listen to the traffic across the warehouse interface (i2) to read its content. (It is anticipated that this be achieved by encrypting all messages.)

In sensitive applications, an eavesdropper can glean useful snippets merely by knowing that there is traffic or knowing its quantity-but this is unlikely to be a concern in commercial environments. If it is, engage a security expert to work out your security requirements.

Documentation and Third-Party Interface Development Requirements

If we own the interface, the developers of the system(s) at the other end will need to know what to do, and it's our responsibility to inform them. This means we need to write some kind of "Interface Developer's Guide" for this interface-even if it's rudimentary. How thorough a job we need to do depends on who they are and how many of them there are: if we're building a product, and lots of customers will be implementing this interface, we'll need a slick and comprehensive guide; we don't want our developers spending all their time explaining it over the phone or in emails. Here's an example requirement for an interface developer's guide:

Open table as spreadsheet

Summary	Definition
Warehouse interface development guide	A development guide shall be written containing sufficient information to allow a competent software engineer with suitable skills to develop software that implements the warehouse interface (i2).

This sort of requirement is very similar to requirements to allow third-party development of drivers, as described in the extendability requirement pattern. See also the documentation requirement pattern, discussed later in this chapter, for further details on what to say.

The external developers also need to be able to test their interface software. This probably means making a test system available for them to use and running it for as long as necessary. If we're writing software to help test the interface, perhaps we can make that available to them-which involves packaging it up neatly. Last, the developer's guide needs to explain all these testing issues. Write requirements covering everything that you decide is needed, and point out suggestions that were rejected.

Considerations for Development

When designing an inter-system interface, start by running through the topics in the list at the start of the "Extra Requirements" section of this pattern. Some of these topics might be covered in requirements, but most probably aren't. A well-rounded interface design and implementation take these matters into account and can cope without panic when changes are made in the future.

Consider writing software to simulate the interface (and the system at the other end). The value of this depends on the importance of the interface (does your company's future depend on it?), its complexity, and the availability of a test system by the other system's owners. Testing error conditions can be difficult and tedious; some are impractical to cause at all. Sometimes it's useful to have the test software simulate certain types of errors. (One system I worked on let us specify, in the messages themselves, the type of error to simulate during testing. This was very powerful. But we had to take great care that all trace of this feature was removed-compiled out-before the software went into production. I'm not promoting this approach.)

Considerations for Testing

The organization who builds a system must test every component, within the system's scope, that participates in the interface. Treat each participating component separately. Identify, from three sources, all the kinds of interaction that can occur across an interface:

1. Explicit interaction requirements (as per the inter-system interaction requirement pattern that follows).

2. Implicit interactions, which help to satisfy goals stated indirectly. For example, resilience, traffic verification and security requirements (and possibly others) might involve additional kinds of interactions.

3. Interactions not discernable from the requirements at all.

See the inter-system interaction requirement pattern that follows for more about how to test each kind of interaction.

Most commonly, one end of an interface is outside the scope of the system being implemented. Check that a test "other end" system is available. Things become tricky and risky if not. This is often an important issue-especially when dealing with big, powerful organizations such as financial institutions (to test, say, credit card transactions) and government bodies. Sometimes, it even becomes necessary to build a working simulation of another system, which can involve considerable extra time and effort.

See the previous "Considerations for Development" section. Encourage the development team to build software to test the interface, and then make use of it. But don't rely on test software of this sort for all testing, in case it's incomplete or doesn't simulate the interface faithfully.