Versions Compared

Version Old Version 27 New Version 28
Changes made by

WILSON Scott

WILSON Scott

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Insert excerpt
Task Status
Task Status
nopaneltrue

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.

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:

The noun/role should be as clear as possible.
  • The verb should be from an agreed list (of examples).

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

    Code Block
    languagejs
    titleExample of SWIM-SERV-140 using Service Metadata Schema
    "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
    titleSWIM-SERV-240

    Note: To improve readability across service descriptions, it is best practice to apply the following conventions for a service interface name

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

    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:

    Example roles using AMQP 1.0 are:

    • Publisher, Queue, Message...

    SWIM-DEFN-270 Service operations

    Advice for naming service operations is given in the note to SWIM-SERV-270.

    Info
    titleSWIM-SERV-270

    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; 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 The AMQP 1.0 standard uses message queues. A service consumer can connect to a specific endpoint (which is user specific) .Depending on whether to include business logic, operations to get a message. 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 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.
    Code Block
    languagejs
    titleExample of SWIM-SERV-100 using Service Metadata Schema
    "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.