Page Table of Content

Requirement

Title	Service operations
Identifier	SWIM-SERV-270
Requirement	A service description shall include or refer to information about the exposed service operations including: the name of the service operation; and a description of the intent and the results of the service operation.
Rationale	The consumer needs to know which service operations are available to be called for the expected result.
Verification	Completeness: Verify that all service operations are described. Consistency: Verify the service operations against the messaging technology needs. Correctness: Not Applicable.
Examples/Notes	Note: Service operations may be grouped under service interfaces. Note: To improve readability across service descriptions, it is best practice to apply following conventions for a service operation name: include a verb and a noun; and be represented using lowerCamelCase. Example service operation names: getAlerts; requestTrajectoryAnalysis; publishAirportMETInducedCapacity; setCoordinationAndTransferData; proposeARESDeActivation; setTargetOffBlockTime. Note: When the operations are used as defined by the protocol selected in SWIM-SERV-260 there is no need to list them in the service description. This covers, for example, the Open Geospatial Consortium's Web Feature Service that has standardised operations. Note: When a service operation has several input parameters, it is best practice to indicate the role of each parameter. Note: It may be considered to include information such as the expected number of elements to be exchanged and their frequencies.
Level of Implementation	Mandatory

Guidance

technical view

The service operations provide a technical view of the interactions with the service.
The service functions described in SWIM-SERV-140 Service functions provide a business view of the interactions with the service.

The requirement is to make known the details about the service operations. In line with many of the other requirements, this can be done in one of two ways:

detailing the operations in the service description;
providing a reference to where details on the operations can be found. This avoids having to duplicate the details in the service description. This is of particular benefit where a service specification such as those issued by the Open Geospatial Consortium is used in SWIM-SERV-250 SWIM TI Profile and interface bindings.

The description of the operation covers the intent and results of the service operation. This can be elaborated in order to cover the full behaviour of the operation.

The specification allows flexibility in describing the technical view of the interactions with the service. This is illustrated below. For example:

some service designs do not rely on interfaces or operations for their interactions. These are described when "exposed".
it is possible to detail the linkages between the items where they exists e.g. an operation will define its input and output message.

Verification Support

Completeness

Check that:

[ ] The service description includes or refers to information about the exposed service operations.

[ ] The information about the service operations includes the name of the service operation.

[ ] The information about the service operations includes a description of the intent and the results of the service operation.

Consistency

Check that:

[ ] The service operations against the messaging technology needs.

Examples

The following example shows the content as a table.

Service operations	operation	operation name	setTOBT
		description	The setTOBT Service Operation receives the Target Off-Block Time for a specific flight. The operation returns a confirmation of the validity of the provided Target Off-Block Time taking into account these business rules: Not accepting values in the past Not accepting a new value too close to the existing one (there is a minimum change involved) Limiting the number of changes after TSAT has been issued
		messages	TOBTSettingRequest, TOBTSettingResponse
	operation	operation name	deleteTOBT
		description	The deleteTOBT Service Operation receives a request for deleting the Target Off-Block Time for a specific flight. The operation returns a confirmation of the validity of such request taking into account this business rule: Not accepting request affecting a flight with no Target Off-Block Time set yet.
		messages	TOBTDeleteRequest, TOBTDeleteResponse

The following example shows an extract of the content of a JSON file that conforms to the Service Metadata Schema

Example of SWIM-SERV-270 using Service Metadata Schema

"serviceInterface": [{
 "operations": [{
  "name": "setTOBT",
  "description": "The setTOBT Service Operation receives the Target Off-Block Time for a specific flight. The operation returns a confirmation of the validity of the provided Target Off-Block Time taking into account these business rules: Not accepting values in the past; Not accepting a new value too close to the existing one (there is a minimum change involved);Limiting the number of changes after TSAT has been issued.",
  "idemptotency": "IDEMPOTENT",
  "messages": [{
   "name": "TOBTSettingRequest",
   "direction": "IN"
  },
  {
   "name": "TOBTSettingResponse",
   "direction": "OUT"
  }]
 },
 {
  "name": "deleteTOBT",
  "description": "The deleteTOBT Service Operation receives a request for deleting the Target Off-Block Time for a specific flight. The operation returns a confirmation of the validity of such request taking into account this business rule: Not accepting request affecting a flight with no Target Off-Block Time set yet.",
  "idemptotency": "IDEMPOTENT",
  "messages": [{
   "name": "TOBTDeleteRequest",
   "direction": "IN"
  },
  {
   "name": "TOBTDeleteResponse",
   "direction": "OUT"
  }]
 }]
}]

Complete examples are available at Example service description.

SWIM Supporting Material

SWIM-SERV-270 Service operations

Requirement

Guidance

Verification Support

Examples