Where do Interface descriptions belong in a spec?

Question

At my job we have a fairly elaborate specifications model. Basically we need to create 3 layers of specifications where each subsequent level elaborates on the previous.

We've got:

• the top layer which is are the requirements
• the middle layer which is the functional spec
• the bottom layer which is the design spec

Usually what goes where is pretty self explanatory. But several times now I've wondered about interface descriptions (file formats, APIs or Databases that are shared with other products/parties) and where they go. Each item in an upper layer must be addressed and elaborated on in each lower layer.

1. You could argue that since a file format received from a third party is immutable it belongs in the top layer. Our internal "customer" has this file format and wants to do something with it. The downside is that all this detail then needs to be mindlessly replicated through all three layers.
2. You could argue that it belongs in the bottom layer whether it is a file format you design yourself or one that is imposed on you from the outside. The requirement is only that you "can handle it".

What's the "official" way to do this?

Answer 1

If you're being rigorous in your interpretation of the three levels, an interface declaration as such would go in the middle level, but it would "extend" into the levels above and below, like this:

Requirement

The ability to export data X into external system Y.

Functional spec

Data export will go through a REST interface with the following endpoints:

...

Design spec

REST interfaces will be implemented via library X, calling services Y...

This would be the same whether you define the interface or you use one that already exists (like a 3rd party file format), except if the interface declaration is already available externally, you will just refer to it in the functional spec, rather than duplicating it.

The above only applies to external interfaces, internal interfaces between different parts of the same system would better be defined in the design spec.

But ultimately what you should think about (as with any documentation) is this: how will this documentation be used? Who is the target audience? Where would I expect a sensible reader to look for the interface specification?

---

Another way to justify specifying this on the functional level is to think of who you are accountable to if you are about to change something.

1. If you change something specified in the design spec, that should be the internal matter of your application. Technically no-one else should know about it. If your system passes all the integration tests, you're fine.
2. If you make a change to something in the functional spec, you'd have to notify all the users of the feature you plan to change, including the external systems connecting to yours.
3. If you make a change on the requirement level...well, you shouldn't, it's up to the business to set the requirements.

Answer 2

This seems pretty subjective. Personally I'd put interface descriptions in the Functional spec (because they are "requirements" rather than "decisions"), or in a separate "appendix" document that doesn't sit on this scale at all. But they'd just as easily fit in the Design spec (because they are implementation details). It's hard to answer this — which, I suppose, is why you've asked it.

The direct answer to your question, though, is that there isn't an "official" way to do it.

Answer 3

We had a similar documentation system for a large information solutions company I worked for.

The details you've described properly sits in the design spec in my view - if not in a level below this.

To summarise why, this is my take on those spec levels:

Requirements

Defines what is required at a high level. The business rules if you like.

Functional spec

Describes at a high level the parts of the system that will deliver the requirements.

Design spec

Describes the detail (i.e. the "how") - the system internals, the logical DB design, the physical DB design. Anything that requires breaking down further goes into a design document/spec below this.

As you've already outlined, you want to avoid having to push detail up through the documentation layers. If you push the detail into the design spec, this is usually fine but there are of course times where there are is a fundamental change that requires changes across the design. It happens - people forget/misunderstand requirements or chunks gets added and removed.

Answer 4

There are a few ways to handle this, but they tend to not belong in a requirements specification or a design specification. This is especially true if you are building the software internally, but need to release your interface documentation to a broader audience. You probably don't want to release all of your software requirements and internal design information to external entities interested in your interfaces.

At work, we use interface requirements specifications (or interface requirements documents) and interface control specifications (or interface control documents). The interface requirements specifications tend to only exist at a system or subsystem level. By the time you are dealing with a software-only component, the interface requirements have been defined, so we'll just include the pertinent information from the higher level specification (either inclusion or trace - both are easy with a requirements management tool).

The advantage of this is that we tend to not release component specifications (requirements or design) to external parties. Software requirements specifications contain requirements levied by the business to support long-term technology development goals as well as internal customers from systems engineering, SQA, manufacturing, and others. These are requirements that we may not want to expose to external customers for a number of reasons (especially constraints or requirements in support of long-term tech development).

The interface control specification or interface control document simply provides a specification for the inputs and outputs between two or more components, subsystems, or systems. How we write these varies. For some products, a component outputs a standard format so we have an ICD for that format and a separate ICD for the input. We can then go and assemble these pieces in different ways for customers, making a sort of volume of documents all linked together.

Something else to keep in mind, a document doesn't necessarily need to be a Microsoft Word or PDF document. A wiki page or collection of wiki pages (with appropriate edit control and revision history, especially with the ability to export to a static format) is just as much a document as other formats. It's more about the content being available and appropriately linked together in a meaningful manner than the way it's ultimately pulled together.

Interface design and control is a practice from Systems Engineering. NASA has an interesting document about the subject. However, depending on your field, it's probably overkill. You may be able to learn from these practices and tailor them to an appropriate level.