Appendix A: Templates for Specification of APIs and API Operations This Annex explains the table templates used for documentation of interfaces, operations, data types, etc. Card. is the cardinality (or multiplicity) defining the lower and upper bound of the number of instances of the member element. "" denotes an arbitrary infinite number of elements of the corresponding Type. "0..1" means optional. "0.." or "0..3" etc. means that the list may be either not available (null object) or empty or has infinitely many / exactly three elements. Note: attributes having a default value are always considered to be optional; there is always a value for the attribute because the default value is used for initialization in this case. Table 1. Interface Description Interface: <Interface Name> Operation Name Description Oper1 Human-understandable description of the operation of the interface. Only major input and output information shall be described, no individual request and result parameters. Note: all words in the service operation name are written together in italics without a blank in between. The first letter of the first word is lower case, all other words are upper case. … operN (optional) Human-understandable description of the operation n of the interface. Optional operations are to be marked by suffix (optional) after the operation name. Template 2. Operation Description Operation Name: Name of the operation: all individual words in the operation name are capitalized Explanation: Human-understandable description of the functionality The operation provides its functionality through the following input and output parameters: Input parameter 1: human-understandable description of the purpose of the input parameter 1 … Input parameter N: human-understandable description of the purpose of input parameter N Output parameter 1: human-understandable description of the purpose of output parameter 1: human-understandable description of the purpose of the input parameter 1 … Output Parameter N: human-understandable description of the purpose of output parameter N: If payload is mentioned as output parameter, only the returned payload in case of a successful operation (status code: Success, SuccessCreated) is denoted in column Type. In case of failure see Generic Status Codes. If no payload is mentioned as output parameter, the status code shall be SuccessNoContent in case of success, otherwise see Clause 0. Convention: all words in the interface name are written together in italics without a blank in between. The first letter of the first word and all other words are written in upper case letters. semanticId The unique identifier of this operation Name Description Mand. Type Card. Input Parameter inputParameter1 Human-understandable description of the input parameter 1 of the operation. States whether the inputParameter1 is mandatory (“yes”) or optional (“no”) Type of the input parameter 1 The cardinality of type of the inputParameter1, e.g. zero-to-one (“0..1”) or at-least-one (“1..*”). … inputParameterN Human-understandable description of the input parameter N of the operation. States whether the inputParameterN is mandatory (“yes”) or optional (“no”) Type of the input parameter N The cardinality of type of the inputParameterN, e.g. zero-to-one (“0..1”) or at-least-one (“1..*”). Output Parameter outputParameter1 Human-understandable description of the output parameter 1 of the operation. States whether the outputParameter1 is mandatory (“yes”) or optional (“no”) Type of the output parameter 1 The cardinality of type of the outputParameter1, e.g. zero-to-one (“0..1”) or at-least-one (“1..*”). … outputParameterN Human-understandable description of the output parameter N of the operation. States whether the outputParameterN is mandatory (“yes”) or optional (“no”) Type of the output eparameter N The cardinality of type of the outputParameterN, e.g. zero-to-one (“0..1”) or at-least-one (“1..*”).