| Insert excerpt |
|---|
| Task Status |
|---|
| Task Status |
|---|
| nopanel | true |
|---|
|
design is a step in the service orientation process detailed on the SWIM reference website
The issue of topics has been discussed in the FAQ. See:
Documenting its use
| Info |
|---|
| title | The overall approach |
|---|
|
| There is no need to rewrite the standards. For example, there is no need to document the operations defined by the standard. It is preferable to refer to where they are documented. |
The following example shows how to document the use of AMQP.
| Code Block |
|---|
| language | js |
|---|
titleorientation-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.
Naming conventions
The following section shows how the names appear in a service definition.
In general:
| Info |
|---|
The following documents will help. |
SWIM-DEFN-140 Service functions
The functionality expresses the business view of the service. The requirements asks for information about:
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:
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.
product-specific description on the delivered product.",
" |
provided continually; the service |
The functionality name could be somehow harmonised for AMQP services or a general term, because it delivers always data.
| Code Block |
|---|
| language | js |
|---|
| title | Example of SWIM-SERV-140 using Service Metadata Schema |
|---|
|
"generalDescription": {
"functionality": [consumer gets the subscribed data."
}, {
"name": " |
description": "...",
"realWorldEffect": "..."
}]
} |
SWIM-
DEFN-240 Service interfaces
Advice on naming service interfaces
Name and description could be harmonised e.g. AMQP Notification, AMQP Subscription.
SWIM-SERV-240 already contains a <noun><role> pattern. e.gis 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 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:
As far as AMQP is converned, 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.
The best practice could be a link to ... specifications to header/content-type information (e.g. AMQP header information to encoding, message-annotation etc.)
| Code Block |
|---|
| language | js |
|---|
| title | Example of SWIM-SERV-250 using Service Metadata Schema |
|---|
|
"serviceInterface": [{
"serviceInterfaceBinding": {
"name": "SWIM_TI_YP_1_1_AMQP_MESSAGING",
"description": "..."
}
} |
A harmonised entry for AMQP delivery. Consider a controlled vocabulary of verbs for names.
SWIM-SERV-280 Service messages270Note: 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) 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.
Categorisation
SWIM-DEFN-100 Service categories
The following example shows how to
| language | js |
|---|
title | add a service categorisation for a Web Feature Service.
| Code Block |
|---|
| Note |
|---|
The URL used in the example does not exist yet. It is waiting for the service category page to be updated. |
FEATURE_ACCESS_SERVICE",
"categorisationScheme": {
|
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: