Requirement

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 

Schema

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

		"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
				}
			}
		},

Rules expressed for the cases as defined in Registry URD.

caserules
COMPLIANTmandatory
CANDIDATEsame
DEFINITIONsame

Guidance

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

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 namedescriptiontypeguidancerule
nameThe name of the interface.stringProvide the actual name of the interfaceMandatory
descriptionThe description of the entity.stringProvide a textual description of the service interface including its purpose.Mandatory
interfaceProvisionSideAn indication that the interface is a provider side interface or a consumer side interface.

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 MessageExchangePatternThe type of primitive MEP implemented by the interface.

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
endPointLocation 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

Additional attributes to Interface type are described in 


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 namedescriptiontypeguidancerule
nameThe 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
descriptionThe description of the entity.stringIf useful, provide additional information on the end-point, such as usage, accessibility, etc.Optional
addressA network-visible identifier used to designate specific endpoints in a network.stringProvide the fully qualified network address at which the interface can be accessedMandatory
addressableResourceA 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 namedescriptiontypeguidancerule
typeThe type of resource.

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
nameThe name of the resource.stringProvide a self descriptive nameMandatory
descriptionThe description of the resource.stringConsider providing additional information that enables to understand the resource ( E.g. For QUEUE the behavior FIFO)Optional

Example

    "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",
                "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"
                    }
                ]
            }
        ],

    }


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