projectdoc Toolbox

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

Documentation Type


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


The document type interface provides the following properties:


Please note that only information about specific properties is provided here. Common document property used by all document types are documented by Document Properties.


Define the unique technical identifier of the interface.


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


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).


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


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.



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.


List the requirements on the interface.

Security Aspects

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


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.


Data and Formats

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


Describe the methods to check data.


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.


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.


The text of notes sections is also indexed.


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.


For further information please refer to References and 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.


For further information please refer to References and Resources.


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