Table of Contents

Requirement

Panel

borderColor	lightgrey
bgColor	whitesmoke
borderStyle	dashed

Title	Service interfaces
Identifier	SWIM-SERV-016
Requirement	A service description shall list the service interfaces (provider side and consumer side 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 following conventions for a service interface name (the appendix B “ISRM naming conventions” of the SESAR 1 Modelling Guidelines [RD 6] is a good source for naming conventions): 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

Examples

See the Interface Overview section and a specific Interface section within the Donlon TOBT Setting Service Description.

Guidance for JSON service description

Excerpt

Include Page

	SCOI:with JSON guidance
	SCOI:with JSON guidance

Schema

The guidance concerns JSON Schema v0.0.3 (see Schema releases).

Expand

title	Schema excerpt [+]

Code Block

language	js

		"InformationService" : 
		{
			"description" : "A type of service that provides an ATM information sharing capability.",
			"type": "object",
			"additionalProperties": false,
			"required": ["descriptionInformation", "name", "version", "serviceAbstract", "serviceProvision", "serviceCategorisation", "serviceGeneralDescription", "serviceInformationDescription", "serviceTechnicalDescription", "serviceDescriptionReferences", "serviceInterface"],
			"properties":
			{

				"serviceInterface":
				{
					"description" : "The means by which the underlying capabilities of a service are accessed.",
					"type" : "array",
					"items" : { "$ref":"#/definitions/Interface" },
					"minItems": 1
				},

			}
		},


		"Interface" : 
		{
			"description" : "The means by which the underlying capabilities of a service are accessed. [SWIM-SERV-016]",
			"type": "object",
			"additionalProperties": false,
			"required": ["name", "description", "interfaceProvisionSide", "tiPrimitiveMessageExchangePattern", "endPoint", "serviceInterfaceBinding", "networkInterfaceBinding", "interfaceBindingDescription", "operation", "behaviour"],
			"properties":
			{
				"name":
				{
					"description" : "The name of the interface. [SWIM-SERV-016]",
					"type" : "string",
					"minLength":1
				},
				"description":
				{
					"description" : "The description of the entity. [SWIM-SERV-016]",
					"type" : "string",
					"minLength":1
				},
				"interfaceProvisionSide":
				{
					"description" : "An indication that the interface is a provider side interface or a consumer side interface. [SWIM-SERV-016]",
					"$ref" : "#/definitions/CodeInterfaceSideType"
				},

				"endPoint":
				{
					"description" : "Location at which information is received to invoke and configure interaction. [SWIM-SERV-016]",
					"type" : "array",
					"items" : { "$ref":"#/definitions/EndPoint" },
					"minItems": 1
				},

			}
		},


		"EndPoint" : 
		{
			"description" : "Location at which information is received to invoke and configure interaction.",
			"type": "object",
			"additionalProperties": false,
			"required": ["address"],
			"properties":
			{
				"name":
				{
					"description" : "The name of the end point.",
					"type" : "string"
				},
				"description":
				{
					"description" : "The description of the entity.",
					"type" : "string"
				},
				"address":
				{
					"description" : "A network-visible identifier used to designate specific endpoints in a network. [SWIM-SERV-016]",
					"type" : "string",
					"minLength":1
				},
				"addressableResource":
				{
					"description" : "A resource that can be addressed through this End Point.",
					"type" : "array",
					"items" : { "$ref":"#/definitions/Resource" },
					"minItems": 1
				}
			}
		},


		"Resource" : 
		{
			"description" : "Anything that can have an identifier. Although resources in general can be anything, SWIM is only concerned with those resources that are relevant to information services and therefore have some additional characteristics. In particular, they incorporate the concepts of ownership and control: a resource that appears in SWIM is a thing that has a name, may have reasonable representations and which can be said to be owned. The ownership of a resource is critically connected with the right to set policy on the resource.",
			"type": "object",
			"additionalProperties": false,
			"required": ["name", "description"],
			"properties":
			{
				"type":
				{
					"description" : "The type of resource.",
					"$ref" : "#/definitions/CodeTechnicalResourceType"
				},
				"name":
				{
					"description" : "The name of the resource.",
					"type" : "string",
					"minLength":1
				},
				"description":
				{
					"description" : "The description of the resource.",
					"type" : "string",
					"minLength":1
				}
			}
		},

Expand

title	Rules [+]

Rules expressed for the cases as defined in Registry URD.

case	rules
COMPLIANT	mandatory
CANDIDATE	same
DEFINITION	same

Guidance

Within field serviceInterface, itself within field informationService, list one or more occurrences of type Interface.

Info
List all interfaces: provider side and consumer side interfaces

Info

title	interface attributes

This requirement addresses many Interface attributes, but not all. The following requirements also involve Interface attributes

requirement	Interface attributes
SWIM-SERV-018 TI Profile and bindings	serviceInterfaceBinding, networkInterfaceBinding, interfaceBindingDescription
SWIM-SERV-019 Protocols and data format	interfaceBindingDescription
SWIM-SERV-021 Service operations	operation
SWIM-SERV-025 Service behaviour	behaviour

See example below

Interface - Mandatory

The means by which the underlying capabilities of a service are accessed.

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

attribute name

description

type

guidance

rule

name

The name of the interface.

string

Provide the actual name of the interface

Mandatory

description

The description of the entity.

string

Provide a textual description of the service interface including its purpose.

Mandatory

interfaceProvisionSide

An indication that the interface is a provider side interface or a consumer side interface.

Expand

title	CodeInterfaceSideType +

An indication that the interface is a provider side interface or a consumer side interface

PROVIDER_SIDE_INTERFACE

An interface provided by the service provider.

CONSUMER_SIDE_INTERFACE

An interface provided by the service consumer.

Select the appropriate value.

Mandatory

tiPrimitive MessageExchangePattern

The type of primitive MEP implemented by the interface.

Expand

title	CodePrimitiveMessageExchangePatternType +

A code listing types of primitive message exchange patterns.

FIRE_AND_FORGET

A primitive MEP consisting of a message being sent from one infrastructure service to another.

SYNCHRONOUS_REQUEST_RESPONSE

A primitive MEP consisting of 1) a message (request) being sent from a consumer infrastructure service to a provider infrastructure service, 2) the consumer infrastructure service remaining blocked awaiting for a response and the provider infrastructure service remaining blocked processing the response and 3) a message (response) being sent from the provider infrastructure service to the consumer infrastructure service.

Select the appropriate value.

Rationale: makes explicit the MEP used by the operations within this interface.

Mandatory

endPoint

Location at which information is received to invoke and configure interaction.

EndPoint

Provide one or more end points.

Provide the end point to be used for operational purpose.
It is best practice to provide, in addition, the endpoint that can be used for testing and development purposes.

Mandatory, minItems=1

e

EndPoint - Mandatory

Location at which information is received to invoke and configure interaction.

Rationale: This information facilitates the the understanding of the location to access the interface.

attribute name	description	type	guidance	rule
name	The name of the end point.	string	Provide a concise name that makes clear the usage of the end-point. Example: "Operational", "Pre-operational evaluation".	Mandatory
description	The description of the entity.	string	If useful, provide additional information on the end-point, such as usage, accessibility, etc.	Optional
address	A network-visible identifier used to designate specific endpoints in a network.	string	Provide the fully qualified network address at which the interface can be accessed	Mandatory
addressableResource	A resource that can be addressed through this End Point.	Resource	Consider providing zero or more additional information to describe the resource that is made available at the endpoint for the consumer to better understand the connection and exchanges with the endpoint. E.g. An endpoint that provides a QUEUE as a resource, can be further described to explain its behaviour e.g. FIFO, LIFO. E.g. An endpoint that provides a REST-RESOURCE indicates the architecture of the service, and the fact that the endpoint can have multiple resources it enables to list all the REST resources available under an endpoint for which all operations of the interface apply (typical of REST architecture)	Optional

Resource - Optional

Consider providing additional information to describe the resource that is made available at the endpoint for the consumer to better understand the connection and exchanges with the endpoint.

Although resources in general can be anything, SWIM is only concerned with those resources that are relevant to information services and therefore have some additional characteristics. In particular, they incorporate the concepts of ownership and control: a resource that appears in SWIM is a thing that has a name, may have reasonable representations and which can be said to be owned. The ownership of a resource is critically connected with the right to set policy on the resource.

E.g. An endpoint that provides a QUEUE as a resource, can be further described to explain its behaviour e.g. FIFO, LIFO,.

E.g. An endpoint that provides a REST-RESOURCE indicates the architecture of the service, and the fact that the endpoint can have multiple resources it enables to list all the REST resources available under an endpoint for which all operations of the interface apply (typical of REST architecture)

attribute name

description

type

guidance

rule

type

The type of resource.

Expand

title	CodeTechnicalResourceType +

An indication that the interface is a provider side interface or a consumer side interface

QUEUE	A staging area that contains messages that have been sent and are waiting to be read.
REST_RESOURCE
SERVICE_REQUEST_LISTENER
TOPIC

Select the applicable value, if any.

Rationale: Indicates the type of the resource: QUEUE, TOPIC,..

Optional

name

The name of the resource.

string

Provide a self descriptive name

Mandatory

description

The description of the resource.

string

Consider providing additional information that enables to understand the resource ( E.g. For QUEUE the behavior FIFO)

Optional

Example

Code Block

language	js

    "informationService": {


		"serviceInterface": [
			{
				"name": "TOBTSettingReceiver",
				"description": "The interface allows setting or deleting the TOBT of the specified flight.",
				"interfaceProvisionSide": "PROVIDER_SIDE_INTERFACE",
				"tiPrimitiveMessageExchangePattern": "SYNCHRONOUS_REQUEST_RESPONSE",
				"serviceInterfaceBinding": "...",
				"networkInterfaceBinding": "...",
				"interfaceBindingDescription": "...",
				"endPoint": [
					{
						"name": "Production Service Endpoint",
						"description": "The service is available for consumption for operational usage at this endpoint",
						"address": "http://www.swim.donlon-airport.com/swim-ops/gateway",
						"addressableResource": [
							{
								"name": "Request Handler",
								"description": "At this endpoint a resource is available to handle service requests",
								"type": "SERVICE_REQUEST_LISTENER"
							}
						]
					},
					{
						"name": "pre-operational evaluation",
						"description": "",
						"address": "http://www.swim.donlon-airport.com/swim-pre-ops/gateway"
					}
				],
				"operation": [...],
				"behaviour": [...]
			}
		]
    }

A complete JSON example is available in page JSON example - Donlon TOBT Setting service description.

Page tree

Versions Compared

Old Version 15

New Version Current

Key

Requirement

Guidance

Examples

Guidance for JSON service description

Schema

Guidance

Interface - Mandatory

EndPoint - Mandatory

Resource - Optional

Example

Page tree

Page History

Versions Compared

Old Version 15

New Version Current

Key

Requirement

Guidance

Examples

Guidance for JSON service description

Schema

Guidance

Interface - Mandatory

EndPoint - Mandatory

Resource - Optional

Example