System interfaces for distribution management –
Part 100: Implementation Profiles. Great advices how to implement WS-interfaces, on your application infrastructure, that comply with the standard. Some notes and thoughts below.
Start from Information Objects
First thing for designing new WS-interfaces is to consider information objects that the new functionalities pertains to. If possible try to find standard that defines objects and their naming conventions (noun) for you. There is a good chance that the same standard defines actors, roles and interaction patterns (verb) in that specific domain. If so, follow them as straight as possible.
Draw interaction and sequence diagrams
Draw interaction and sequence diagrams based on the use cases the interfaces are meant to be used for.
Define Service Semantics
Based on the diagrams, services are identified for the entire message flow. The naming of the services are based on their service pattern (based on the role in entire flow). Each service will have the same operation as indicated in the diagrams as messages, but have different service name.
Conventions for version controling
Use targetNamespace and version attributes to define the version of the used schema or wsdl.
<definitions version="1.0" targetNamespace="http://ORGANISATION/DOMAIN/STANDARD/RELEASE DATE OR YEAR/SERVICE PATTERN NAME + NOUN">
<xs:schema targetNamespace="http://ORGANISATION/DOMAIN/STANDARD/RELEASE DATE OR YEAR/VERB + NOUN" version="1.0">
Add detailed version information with annotations
<xs:schema targetNamespace="http://ORGANISATION/DOMAIN/STANDARD/RELEASE DATE OR YEAR/VERB + NOUN" version="1.1">
<xs:annotation>
<xs:documentation>
Major version 1.0 created in 2013/03/12
Minor version 1.1 created in 2013/03/13 - one optional element added for the object xxx
</xs:documentation>
</xs:annotation>
Don't change targetNamespace in the minor backward compatible changes to avoid unnecessary WS-client rebuild. Data types are typically defined in the external schema files and imported in wsdl instead of being embedded for better version control.
Conventions for the wsdl
Service and operation naming patterns can be used to implement strictly typed web services.
Wrapped Document style is normally used.
- document style means an XML document is included in a soap message. In the normally case, it is directly placed in the <soap:body>
- if wsdl:operation name is the same as the input element name wsdl is considered as wrapped document style wsdl
- The input message has a single part
- The part is an element
- The element has the same name as the operation
- The element's complex type has no attributes
Operation name follows the Verb + Noun naming convention. The plural form of the information object name is used as a noun to avoid collisions within the xsd. For example CreateEndDeviceEvents
Service name - <Service pattern name>+<Noun>. For example ReceiveEndDeviceEvents
Service patterns can be defined from used standard or the use cases the new interfaces are meant to be used for.
Role of the actor (service provider) in the message flow defines which service name pattern to use
Some common service naming conventions
Send
To provide (send) information (information object) for public (enterprise) consumption. To be invoked by the system of record for the business object and only when the state of the business object has changed. This is normally used in conjunction with the verbs created, changed, closed, canceled and deleted. If ESB integration pattern that loosely couples the service provider and the consumer is used this naming pattern is applied with the interface the ESB provides for the consumers.
Receive
To consume (receive) information (business object) from an external source. This is used in conjunction with the verbs created, changed, closed, canceled and deleted. If ESB integration pattern that loosely couples the service provider and the consumer is used this naming pattern is applied with the interface the ultimate service provider provides.
Request
To request another party to perform a specific service. This is used in conjunction with the verbs get, create, change, close, cancel and delete. If ESB integration pattern that loosely couples the service provider and the consumer is used this naming pattern is applied with the interface the ESB provides for the consumers.
Execute
To run a service provided to the public, which may include a state change request or a query request. This is used in conjunction with the verbs create, change, close, cancel and delete. If ESB integration pattern that loosely couples the service provider and the consumer is used this naming pattern is applied with the interface the ultimate service provider provides.
Reply
To reply with the result of the execution of a service (by the Execute service). This is used in conjunction with the verbs created, changed, closed, canceled and deleted.
Show
To provide (show) information (business object) for public (enterprise) consumption, when the state of the business object is not changed, by the system of record or other system that has a copy of the same business object.
Retrieve
To request specific data of a business object to be provided.
Create template xsd:s and wsdl:s
Create (or use those ones that comes with the used standard) template xsd:s and wsdl:s to support commonly used interaction patterns in your organisation. These templates will help you to follow selected best practices and reduce time consumed to produce new interface definitions.
No comments:
Post a Comment