SWIM Supporting Material

SWIM-SERV-240 Service interfaces

Owned by WILSON Scott
Last updated: 2024 Jun 10
Page Table of Content

Requirement

Title

Service interfaces

Identifier

SWIM-SERV-240

Requirement

A service description shall include or refer to information about the exposed service interfaces, including for each service interface:

  • the name of the service interface;
  • a textual description of the service interface including its purpose;
  • an indication that the interface is a provider side interface or a consumer side interface; and
  • for a provider side interface, the fully qualified network address at which the interface can be accessed.

Rationale

This information facilitates the unambiguous identification of the interface, the understanding of its purpose, and the location to access it.

Verification

Completeness: Verify that the list of interfaces is included; verify that the name, description and indication are included for each interface.

Consistency: For each provider side interface, verify that the network address is provided.

Correctness: Not Applicable.

Examples/Notes

Note: To improve readability across service descriptions, it is best practice to apply the following conventions for a service interface name

  • be represented using UpperCamelCase; and
  • use the <noun> <role> pattern where <noun> is a topic related to the service and <role> describes the roles in a composition/interaction sequence, based on the Message Exchange Pattern that is used.

Example service interface names: FlightPlanCoordinator, FlightPlanSubmitter, ForecastProvider, ForecastConsumer, ClearanceRequester,     ClearanceManager, PreDepartureSequencer, FlightInformationPublisher, AlertListener.

Note: It is best practice to provide, in addition, the network address(es) for accessing the service instance(s) that can be used for testing and development purposes.

Level of Implementation

Mandatory

Guidance

The specification makes the definition of at least an network address (endpoint) mandatory. Therefore, it is not possible to simply ignore the need for a network address.

This leads to two situations:

  • The network address is withheld, for example, for security reasons. The description of the endpoint can then be used to say e.g. “For security reasons, the addresses will be communicated only to customers” when a formal arrangement (such as a service level agreement) is agreed.
  • Each service consumer has a dedicated endpoint. The specification allows multiple endpoints. It is therefore possible to use parameterized URLs (to illustrate: https://www.domain.com/url?variable=value&variable=value). The use of parameterized URLs is very common. The description of the endpoint can then be used to say that the parameters will be assigned to the consumer when a formal arrangement (such as a service level agreement) is agreed.

Verification Support

Completeness

Check that:

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

[  ] The  information about the exposed service interfaces includes the name of the service interface.

[  ] The  information about the exposed service interfaces includes a textual description of the service interface including its purpose.

[  ] The  information about the exposed service interfaces includes an indication that the interface is a provider side interface or a consumer side interface.

Consistency

Check that:

[  ] For each provider side interface, verify that the network address is provided.

Examples

The following example shows the content as a table.

service interfaces

interfacenameTOBTSettingReceiver
description

The interface allows setting or deleting the TOBT of the specified flight using SynchronousRequestReply.

provider/consumer sideProvider side interface
network addresshttp://www.swim.donlon-airport.com/swim-ops/gateway

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

Example of SWIM-SERV-240 using Service Metadata Schema
"serviceInterface": [{
 "name": "TOBTSettingReceiver",
 "description": "The interface allows setting or deleting the TOBT of the specified flight using SynchronousRequestReply.",
 "provisionSide": "PROVIDER_SIDE",
 "endpoints": [{"url": "http://www.swim.donlon-airport.com/swim-ops/gateway"}]
}]
Example of SWIM-SERV-240 using Service Metadata Schema
"serviceInterface": [{
 "name": "TOBTSettingReceiver",
 "description": "The interface allows setting or deleting the TOBT of the specified flight using SynchronousRequestReply.",
 "provisionSide": "PROVIDER_SIDE",
 "endpoints": [{"url": "url:withheld", "description": "For security reasons, the addresses will be communicated only to customers."}]
}]


Complete examples are available at Example service description.

Status: Living Material