By internal interface we mean the interface between building blocks within a system, in contrast to external interfaces that connects our system to the external world.

You have a number of options, shown below with increasing degree of detail and effort:

  1. Show the interface by any connection (line) within a whitebox diagram.
  2. Give the interface a (hopefully self-describing) name (aka aptronym).
  3. Describe the name informally (e.g. within a table below the respective whitebox diagram) with one or two sentences.
  4. Document the interface and its usage by one or more unit-tests. The idea behind those tests should be “test-as-documentation”. On one hand these tests are precise, on the other hand they shouldn’t add much overhead to your work, as you will write some unit tests anyway (at least we hope so…)
  5. Add the programming interface (API): list methods or functions with the required/optional parameters.
  6. Add further UML details to your whitebox diagram, e.g. ball-socket, ports, and describe those within your modeling tool.
  7. Add quality attributes of this interface to the API description, e.g. performance or throughput guarantees. Some people call those the “service level agreements” of the interface.

I like to emphasize the usefulness of test-as-documentation: It’s a developer-friendly and pragmatic way of documenting potentially critical elements of your architecture. Those tests will (hopefully) be automatically included into your documentation - so the documentation is always correct.