Working towards the next version of the SWIM Supporting Material

Page tree

Working towards the next version of the SWIM Supporting Material

Skip to end of metadata
Go to start of metadata


Requirement

Title

Service operations

Identifier

SWIM-SERV-021

Requirement

A service description shall include a technical description of the service operations of each of its interfaces, including:

  • the name of the service operation;
  • a description of the intent and the results of the service operation; and
  • a description of the exchanged information by the service operation, including the input, output and error messages.

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: 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.

Note: For readability and understanding of services implemented using REST methods, it is best practice to define logical operations and to map these to the underlying REST methods being used.

Note: In case of subscription in a Publish / Subscribe message exchange pattern, the management of subscriptions must be specified, including the use and management of subscription id, the mechanism to unsubscribe, etc.

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

Examples

See the Service Operations section within the Donlon TOBT Setting Service Description.

Guidance for JSON service description 

Unable to render {include} The included page could not be found.

Schema

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

		"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":
			{

				"operation":
				{
					"description" : "Specification of a transformation or query that an object may be called to execute. [SWIM-SERV-021]",
					"type" : "array",
					"items" : { "$ref":"#/definitions/Operation" },
					"minItems": 1
				},

			}
		},


		"Operation" : 
		{
			"description" : "Specification of a transformation or query that an object may be called to execute.",
			"type": "object",
			"additionalProperties": false,
			"required": ["name", "description", "operationMessage"],
			"properties":
			{
				"name":
				{
					"description" : "The name of the operation. [SWIM-SERV-021]",
					"type" : "string",
					"minLength":1
				},
				"description":
				{
					"description" : "The description of the operation.",
					"type" : "string",
					"minLength":1
				},
				"idempotency":
				{
					"description" : "A value that indicates whether the operation is \"idempotent\" or \"non-idempotent\". [SWIM-SERV-021]",
					"$ref" : "#/definitions/CodeIdempotencyType"
				},
				"synchronicity":
				{
					"description" : "A value that indicates whether the operation is \"synchronous\" or \"asynchronous\". [SWIM-SERV-021]",
					"$ref" : "#/definitions/CodeSynchronicityType"
				},
				"tiProtocolMethod":
				{
					"description" : "A protocol method used to implement the operation.",
					"type" : "array",
					"items" : { "type":"string" },
					"minItems": 1
				},
				"precondition":
				{
					"description" : "A description of the state or condition that should be true before the operation can proceed.",
					"type" : "string"
				},
				"processingConsideration":
				{
					"description" : "A step, constraint or action that is required to be taken on data received as part of a service request (input) in order to produce the desired output or change of internal state.",
					"type" : "array",
					"items" : { "$ref":"#/definitions/ProcessingConsideration" },
					"minItems": 1
				},
				"operationMessage":
				{
					"description" : "A message associated with the operation. [SWIM-SERV-021]",
					"type" : "array",
					"items" : { "$ref":"#/definitions/Message" },
					"minItems": 1
				}
			}
		},


		"ProcessingConsideration" : 
		{
			"description" : "A step or action that is required to be taken on data received as part of a service request (input) in order to produce the desired output or change of internal state.",
			"type": "object",
			"additionalProperties": false,
			"required": ["name", "description"],
			"properties":
			{
				"name":
				{
					"description" : "The name of the processing consideration.",
					"type" : "string",
					"minLength":1
				},
				"description":
				{
					"description" : "The description of the processing consideration.",
					"type" : "string",
					"minLength":1
				}
			}
		},




		"Message" : 
		{
			"description" : "A discrete unit of communication intended by the source for consumption by a given recipient or group of recipients.",
			"type": "object",
			"additionalProperties": false,
			"required": ["direction", "name"],
			"properties":
			{
				"direction":
				{
					"description" : "A value that indicates whether the message is \"input\" or \"output\".  [SWIM-SERV-021]",
					"$ref" : "#/definitions/CodeDirectionType"
				},
				"name":
				{
					"description" : "The name of the message. [SWIM-SERV-021]",
					"type" : "string",
					"minLength":1
				},
				"description":
				{
					"description" : "The description of the message.",
					"type" : "string"
				},
				"isFault":
				{
					"description" : "An indication whether the message is a fault or not. [SWIM-SERV-021]",
					"type" : "boolean"
				},
				"headers":
				{
					"description" : "The description of the headers.",
					"type" : "string"
				},
				"body":
				{
					"description" : "The description of the body.",
					"type" : "string"
				}
			}
		},

Rules expressed for the cases as defined in Registry URD.

caserules
COMPLIANTmandatory
CANDIDATE
DEFINITION

Guidance

Additional attributes to Interface type as described in SWIM-SERV-016 Service interfaces

technical view

The service operations provide with a technical view of the interactions with the service.

The service functions provide with a business view of the interactions with the service (see SWIM-SERV-012 Service functionality)

Interface - additional attribute

attribute namedescriptiontypeguidancerule
operationSpecification of a transformation or query that an object may be called to execute.Operation

Provide a technical description for all (one or more) service operations of the interface.

Rationale: The consumer needs to know which service operations are available to be called for the expected result.

Mandatory, minItems=1

Operation - Mandatory

Specification of a transformation or query that an object may be called to execute.

attribute namedescriptiontypeguidancerule
nameThe name of the operation.string

Provide the name of the operation.

Note: For readability and understanding of services implemented using REST methods, it is best practice to define logical operations and to map these to the underlying REST methods being used.

Mandatory
descriptionThe description of the operation.stringProvide a description of the intent and the results of the service operation; andMandatory
idempotencyA value that indicates whether the operation is "idempotent" or "non-idempotent".

A code indicating whether the operation is "idempotent" or "non-idempotent".


IDEMPOTENT 

A type of operation in which receiving duplicates of a given message will not cause any undesirable effect.

NON_IDEMPOTENT 

 A type of operation in which receiving duplicates of a given message may cause an undesirable effect.
Optionally, select the appropriate code value.Optional
synchronicityA value that indicates whether the operation is "synchronous" or "asynchronous".

A code indicating whether the operation is "synchronous" or "asynchronous".

SYNCHRONOUS 

A type of operation whose message exchange pattern describes temporally coupled or "lock-step" interactions, e.g., remote procedure call (RPC)-style request-response interactions.

ASYNCHRONOUS 

 A type of operation whose message exchange pattern allows messages to be sent without precise sequencing, e.g., a flow of sensor event messages which need not be individually acknowledged.
Optionally, select the appropriate code value.Optional
tiProtocolMethodA protocol method used to implement the operation.string

Optionally, provide the protocol method being used, such as the HTTP method.

Example: HTTP GET, HTTP POST.

Optional, minItems=0
preconditionA description of the state or condition that should be true before the operation can proceed.string

Describe the pre-condition(s) to execute the operation.

Optional
processingConsiderationA step, constraint or action that is required to be taken on data received as part of a service request (input) in order to produce the desired output or change of internal state.ProcessingConsideration

Provide zero or more processing considerations relevant for service consumers.

This may be expressed as business rule(s).

Optional, minItems=0
operationMessageA message associated with the operation.Message

Describe the information exchanged by the service operation, as one or more input, output or error messages.

Mandatory, minItems=1


ProcessingConsideration - Optional

step or action that is required to be taken on data received as part of a service request (input) in order to produce the desired output or change of internal state.

Consider indicating all constraints that further qualify a service operation (e.g. It does not accept request for a date in the past, or an update that is too close to the current value, or a certain frequency of request).


attribute namedescriptiontypeguidancerule
nameThe name of the processing consideration.stringProvide a self descriptive name.Mandatory
descriptionThe description of the processing consideration.stringExplain the constraint in sufficient detail (e.g. It does not accept request for a date in the past, or an update that is too close to the current value, or a certain frequency of request).Mandatory

Message - Mandatory

A discrete unit of communication intended by the source for consumption by a given recipient or group of recipients.

A type of message exchanged by the service operation

attribute namedescriptiontypeguidancerule
directionA value that indicates whether the message is "input" or "output".

A code that indicates whether the message is "input" or "output".

IN 

Message data is entered into the system.

OUT 

Message data is transferred out of the system.

Select the code value corresponding to the direction of the message:

  • IN = input to the operation
  • OUT = output of the operation
Mandatory
nameThe name of the message.string

Provide the name of the message.

Note: this name will make the link to the information definition.

Mandatory
descriptionThe description of the message.string

Optionally provide a description of the message.

Note: The message description is optional in the service description, but is mandatory in the information definition.

Optional
isFaultAn indication whether the message is a fault or not.booleanOptionally indicate whether the message is an error message.Optional
headersThe description of the headers.stringConsider indicating those headers that are important for processing the message (E.g. Content Type XML, JSON, Content Enconding GZIP,..)Optional
bodyThe description of the body.stringConsider indicating the detailed structure of the payload. E.g. AIXM_v.5.1.1.AIXM.AIXM Features.AirportHeliport.Airport/HeliportOptional

Example

		"serviceInterface": [
			{

				"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 the processing considerations.",
						"idempotency": "IDEMPOTENT",
						"synchronicity": "SYNCHRONOUS",
						"precondition": "No preconditions identified",
						"tiProtocolMethod": [
							"HTTP POST"
						],
						"processingConsideration": [
							{
								"name": "Historic values constraint",
								"description": "The operation does not accept values in the past"
							},
							{
								"name": "New Value Difference Constraint",
								"description": "Not accepting a new value too close to the existing one (there is a minimum change involved)"
							},
							{
								"name": "TSAT issued constraint",
								"description": "Limiting the number of changes after TSAT has been issued"
							}
						],
						"operationMessage": [
							{
								"direction": "IN",
								"name": "TOBTSettingRequest",
								"description": "Message which provides the Target Off-Block Time value of a specific flight.",
								"isFault": false,
								"headers": "application\/XML",
								"body": ""
							},
							{
								"direction": "OUT",
								"name": "TOBTSettingResponse",
								"description": "Message which responds the validity of a previously sent TOBTSettingRequest message",
								"isFault": false,
								"headers": "application/XML",
								"body": "none"
							}
						]
					},
					{
						"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.",
						"idempotency": "IDEMPOTENT",
						"synchronicity": "SYNCHRONOUS",
						"precondition": "",
						"tiProtocolMethod": [
							"HTTP POST"
						],
						"operationMessage": [
							{
								"direction": "IN",
								"name": "TOBTDeleteRequest",
								"description": "Message which requests deleting the last TOBT value of the specified flight.",
								"isFault": false,
								"headers": "",
								"body": ""
							},
							{
								"direction": "OUT",
								"name": "TOBTDeleteResponse",
								"description": "Message which responds the validity of a previously sent TOBTDeleteRequest message",
								"isFault": false,
								"headers": "",
								"body": ""
							}
						]
					}
				],

			}
		],



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

  • No labels