| Insert excerpt | ||||||
|---|---|---|---|---|---|---|
|
| Table of Contents |
|---|
Introduction
Service design is a step in the service orientation process detailed on the SWIM reference website (https://reference.swim.aero/knowledge/service-orientation-process.html#design). One outcome is a service model (service interface(s), service operation(s), service behaviour).
This page provides guidance on some aspects of service design.
| Table of Contents |
|---|
Naming conventions
The following section shows how the names appear in a service definition.
In general:
nouns/roles should be as clear as possible.
verbs should be from an agreed list (of examples).
| Info |
|---|
The following documents will help. |
In general:
Naming conventions
The following section shows how the names would appear in a service definition.
SWIM-DEFN-140 Service functions
The functionality expresses the business view of the service. The requirements asks for information about:
the functions expected to be offered by the service in support of its capabilities; and
their expected real world effects.
The service metadata schema introduces the need to name the function.
Natural language is preferred when naming the function.
The example below uses two formulations:
Provide ...
... Provision
It is not possible to have a best practice on which is preferred. Both formulations are allowed. The important this to remember is that it is a name and should be as clear and descriptive as possible.
Example of SWIM-SERV-140 using Service Metadata Schema
| Code Block | ||
|---|---|---|
| ||
"generalDescription": {
"functionality": [{
"name": "Provide Turbulence Forecast Information",
"description": "A detailed and product-specific description on the delivered product.",
"realWorldEffect": "Information is provided continually; the service consumer gets the subscribed data."
}, {
"name": "Meteorological Forecast Provision",
"description": "...",
"realWorldEffect": "..."
}]
} |
SWIM-DEFN-240 Service interfaces
Advice on naming service interfaces is given in the note to SWIM-SERV-240.
A service may contain multiple interfaces. Some of these may be private or at least interfaces for specific purposes, e.g. Monitoring or Reporting interfaces.
Only exposed service interface need to be documented
.
| Info |
|---|
SWIM-SERV-240Note: To improve readability across service descriptions, it is best practice to apply the following conventions for a service interface name
Example service interface names: FlightPlanCoordinator, FlightPlanSubmitter, ForecastProvider, ForecastConsumer, ClearanceRequester, ClearanceManager, PreDepartureSequencer, FlightInformationPublisher, AlertListener. |
| Info |
|---|
It is best to avoid mention of a broker. Indeed, a broker is not necessary when using AMQP. |
Examples based on this from the SWIM Registry:
TurbulenceForecastPublisher for https://eur-registry.swim.aero/services/dwd-turbulence-amqp-10
ArrivalSequenceInformationPublisher for https://eur-registry.swim.aero/services/dsna-arrivalsequencedistribution-service-v11
NowCastSatRequest for https://eur-registry.swim.aero/services/dwd-nowcastsat-wfs-10
As far as WFS is concerned, what are the roles?
- Request...
As far as AMQP is concerned, what are the roles?
- Publisher, Queue, Message...
SWIM-DEFN-270 Service operations
Advice for naming service operations is given in the note to SWIM-SERV-270.
| Info |
|---|
SWIM-SERV-270Note: 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; setTargetOffBlockTime. |
An example of this convention can be seen in the Web Feature Service standard's getFeature, getCapabilities and getFeatureType operations.
The AMQP 1.0 standard uses message queues. A service consumer can subscribe to a specific endpoint (which is user specific)
Depending on whether to include business logic, operations could be:
- publishMessageTopic
- publishMessageQueue
or with some business logic:
- publishTurbulenceForecastMessageTopic
- publishTurbulenceForecastMessageQueue
to get a message.
Operations from the service provider point of view, e.g., when a broker is used (see BROKERED_PUBLISH_SUBSCRIBE_WITH_PUSH_MECHANISM) could be publishTurbulenceForecast. The use of the broker should be transparent to the service consumer.
| Info |
|---|
Note that there is no need to document operations if a standardised implementation is used. See |
Documenting the use of standardised implementations for more information. |
Categorisation
SWIM-DEFN-100 Service categories
The following example shows how to add a service categorisation for a Web Feature Service.
| Note |
|---|
The URL used in the example does not exist yet. It is waiting for the service category page to be updated. |
Example of SWIM-SERV-100 using Service Metadata Schema
| Code Block | ||
|---|---|---|
| ||
"serviceCategorisation": {
"other": [{
"name": "SERVICE_TYPE",
"value": "FEATURE_ACCESS_SERVICE",
"categorisationScheme": {
"url": "http://reference.swim.aero/information-services/service-categories/CodeServiceType"
}
}]
} |
Application Message Exchange Patterns
SWIM-DEFN-210 Application message exchange pattern
Guidance on the selection of the application message exchange pattern can be found on the SWIM reference resource pages.
In general:
Web Feature Services use one of the REQUEST-REPLY options that are mention in the CodeApplicationMessageExchangePatternType scheme.
Service that are built around AMQP 1.0 use the PUBLISH-SUBSCRIBE options.