Working towards the next version of the SWIM Supporting Material
Working towards the next version of the SWIM Supporting Material
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:
|
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:
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
Schema
The guidance concerns JSON Schema v0.0.3 (see Schema releases).
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 name | description | type | guidance | rule |
---|---|---|---|---|
operation | Specification 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 name | description | type | guidance | rule |
---|---|---|---|---|
name | The 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 |
description | The description of the operation. | string | Provide a description of the intent and the results of the service operation; and | Mandatory |
idempotency | A value that indicates whether the operation is "idempotent" or "non-idempotent". | Optionally, select the appropriate code value. | Optional | |
synchronicity | A value that indicates whether the operation is "synchronous" or "asynchronous". | Optionally, select the appropriate code value. | Optional | |
tiProtocolMethod | A 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 |
precondition | A 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 |
processingConsideration | 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. | ProcessingConsideration | Provide zero or more processing considerations relevant for service consumers. This may be expressed as business rule(s). | Optional, minItems=0 |
operationMessage | A 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 name | description | type | guidance | rule |
---|---|---|---|---|
name | The name of the processing consideration. | string | Provide a self descriptive name. | Mandatory |
description | The description of the processing consideration. | string | Explain 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 name | description | type | guidance | rule |
---|---|---|---|---|
direction | A value that indicates whether the message is "input" or "output". | Select the code value corresponding to the direction of the message:
| Mandatory | |
name | The name of the message. | string | Provide the name of the message. Note: this name will make the link to the information definition. | Mandatory |
description | The 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 |
isFault | An indication whether the message is a fault or not. | boolean | Optionally indicate whether the message is an error message. | Optional |
headers | The description of the headers. | string | Consider indicating those headers that are important for processing the message (E.g. Content Type XML, JSON, Content Enconding GZIP,..) | Optional |
body | The description of the body. | string | Consider indicating the detailed structure of the payload. E.g. AIXM_v.5.1.1.AIXM.AIXM Features.AirportHeliport.Airport/Heliport | Optional |
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.