SWIM Supporting Material

Working towards the next version of the SWIM Supporting Material

Page tree

Versions Compared

Old Version 16

changes.mady.by.user Scott Wilson

Saved on

compared with

New Version Current

changes.mady.by.user Scott Wilson

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Panel
titlePage Table of Content

Table of Contents

Info
titleVersion

This page concerns v2.0 of the Specification. Supporting material on v1.0 is SWIM-SERV-021 Service operations

Requirement

Panel
borderColorlightgrey
bgColorwhitesmoke
borderStyledashed

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

Info
titletechnical 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.
messagesTOBTDeleteRequest, TOBTDeleteResponse

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

Code Block
languagejs
titleExample 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.