| 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 leads to consideration on how to name things.
The following documents will help.
- 08.03.10_D45_ISRM_Modelling_Guidelines.docx
- 20191104 Controlled verbs for Application Functions V.1.1.pdf
Naming conventions
The following section shows how the names would appear in a service definition.
SWIM-DEFN-140 Service functions
The functionality name could be harmonised.
The functionality expresses the business view of the service. Natural language is preferred.
| 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 | ||
|---|---|---|
| ||
Note: 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 (not AMQP but shows the same pattern for names).
- NowCastSatRequest for https://eur-registry.swim.aero/services/dwd-nowcastsat-wfs-10
Example roles in a WFS:
- Request...
Example roles using AMQP 1.0:
- Publisher, Queue, Message...
SWIM-DEFN-270 Service operations
Advice for naming service operations is given in the note to SWIM-SERV-270.
| Info | ||
|---|---|---|
| ||
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; setTargetOffBlockTime. |
An example of this convention can be seen in the Web Feature Service standard's getFeature, getCapabilities and getFeatureType operations.
When you are a consumer, you can subscribe to an existing topic(exchange) on an exposed endpoint or connect to a specific endpoint (which is user specific).
Depending on whether to include business logic, operations from the service provider point of view could be:
- publishMessageTopic
- publishMessageQueue
or with some business logic:
- publishTurbulenceForecastMessageTopic
- publishTurbulenceForecastMessageQueue
| Info |
|---|
| Note that there is no need to document operations if a standardised implementation is used. See 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.
| Code Block | ||||
|---|---|---|---|---|
| ||||
"serviceCategorisation": {
"other": [{
"name": "SERVICE_TYPE",
"value": "FEATURE_ACCESS_SERVICE",
"categorisationScheme": {
"url": "http://reference.swim.aero/information-services/service-categories/CodeServiceType"
}
}]
} |
To describe an implemented service that uses AMQP 1.0 in an harmonised way it would be good to visit the categorisation schemes and indicate which of the elements in the relevant schemes are expected to be used. For instance: CodeApplicationMessageExchangePatternType.PUBLISH_SUBSCRIBE etc..in general would expect on this page also categorisation related information.