Interfaces document how elements of the system communicate with elements of this and other systems.

ID
interface
Suite
Software Development
Documentation Type
Q4 - System
Categories
/ Process / Design
Tags

Description

Interfaces document how elements of the system communicate with elements of this and other systems.

Properties

The document type interface provides the following properties:

Identifier

Define the unique technical identifier of the interface.

Version

Specify the version of the interface that is described by this document.

Type

Define the type of the interface which may be internal (used by components of the system you design) or external (also used by components outside the system you design).

Level

The level is relevant if you want to document an interface by individual parts.

Reference

Add references to information on external systems here.  This is useful if the documentation for an interface is defined elsewhere or may be provided by the interface on-demand.

Sections

Description

Give a summary on the interface.

Business Context

Describe the functionality of the interface from the business point of view.

Business Processes

Describe the business processes relevant for this interface.

Interface Data

Describe the data in its technical context.

Requirements

List the requirements on the interface.

Security Aspects

Describe the security aspects to consider when publishing and using the interface.

Quantities

Define the quantities serviced by this interface. This addresses figures concerned e.g. with

  • Runtime
  • Throughput/Volume
  • Availability
  • Logging
  • Archiving

Participating Resources

Resources affected when this interface is used.

Syntax

Data and Formats

Define the data formats, validity and plausibility rules, encoding, character sets, and configuration data.

Methods/Functions

Describe the methods to check data.

Sematics

Describe the side effects and consequences.

Technical Infrastructure

Document the technical protocols.

Error and Exception Handling

Document the codes and handling of error and exception cases.

Constraints and Assumptions

Document access rights, temporal constraints, parallel access, and preconditions for using the interface.

Operating the Interface

Document the interface from the operation point of view.

Meta Information

Document the person in charge, costs of using the interface, organizational issues, and versioning.

Architecture Decisions

Document the architectural decisions made for the interface.

Examples of Using the Interface

Provide some examples to help users to get started with using the interface.

This may be use cases as well as coding examples.

Subordinate Interfaces

Complex interfaces may be subdivided into single interfaces.

Notes

These are internal notes that are usually not exported and only visible to team members with write access.

But this is not a safe place to store sensible information. It is just a convenience for the reader to not be bothered with notes stored here for the authors for later use. The security level is about suppressing the representation by a CSS style. Therefore consider this as a convenience for the reader, not as a security tool.

References

For a document the references section contains pointers to resources that prove the statements of the document.

Often these proofs are not easily distinguishable from further information. In this case you may want to skip the reference section in favour for the resource list.

Resources

The resources section provides references to further information to the topic of the document.

This may be information on the internet provided by the resource or information in the team's information systems. Anything the reader of the resource might want to know, may be listed here.

Details

This doctype is based on information provided by the arc42 Template.