The interfaces I document are usually service contracts to services exposed to external systems.

If I document in Word, I list keep a table that briefly describes each service, along with a reference to a separate service specification document.

But as I’m more and more often building my architecture documentation as a hierarchy of Confluence pages, I prefer to specify the interfaces in child pages under this one. And then I use this page to convey any common principles for using the services.

Such commonalities often go hand in hand with corresponding design principles, for example the reoccurring system and service version information in requests and responses, the demand for providing and capturing dual identifiers etc.

Each interface or service request typically require a table with the following columns:

FieldFormatValidationDescriptionDesign notes
ServiceHeaderMandatory.Identifies the caller.
CallerNameenum: SystemX, SystemY, SystemZMandatory.

CallerVersionstring, min length: 1, max length: 32Mandatory.
This is a sample service request specification.

I won’t attempt to present a technically accurate specification – developers of the external systems will receive a proper WSDL file to that end. This specification is aimed at SMEs, BAs, TMs and my own developers by providing a easily understandable view of each interface.

I find that such specifications supports requirements analysis activities better than truly technically correct specs, and they also tend to help developers because I can add design notes that have no place in the WSDL files.