What is in a Good Contract? Designing Interfaces for Distributed Systems
Download as ODP, PDF0 likes1,644 views
The document discusses characteristics of good service contracts for distributed systems. It outlines goals for contract design including technology agnosticism, abstraction, reusability, and maintainability. It also discusses XML service guidelines, evaluating example contracts, security policies, and test-driven development approaches for contracts. Key aspects of good contracts identified are having no implementation technology exposed, contract-first design, intuitive naming, qualified elements, accommodating interoperability issues, namespace versioning, consistency with the data model, and decoupling non-functional aspects.
What is in a Good Contract? Designing Interfaces for Distributed Systems
- 1. What is in a Good Contract? Designing Interfaces for Distributed Systems Schalk W. Cronjé ysb33r @ gmail.com @ysb33r
- 2. Service Contract Decouples service implementation details from clients Allows clients to be developed against standardised data models and message structures Provides conditions for access Service Implementation Client Implementations
- 3. Contents Goals for service contract design
- 4. XML services
- 7. TDD & Service Contracts
- 8. What makes a good contract?
- 9. Goals for Service Contract Design © Greco @ skiboardsonline.com
- 10. Intrinsic Interoperability which are containing Highly standardised technical contracts Shared common expressions & data models Designed consistently
- 11. Implementation Technology Agnostic Expression without vendor-specific details
- 12. Avoid vendor lock-in within contract
- 14. Federation Consistent endpoints on technical service portfolio boundary
- 15. Business & Technology Alignment Business-centric services
- 16. Express business logic in close alignment with business analysis
- 17. Production of conceptual versions before physical design
- 18. Abstraction Turn service into black box
- 19. Contract is the only official published source
- 20. Exposure of only essential information
- 21. Reusability Ability to re-use service for service composition and routing
- 22. Forces decision on granularity of service
- 23. Do one thing and do it well
- 24. Statelessness Minimise resource consumption
- 25. Defer management of state information to a better suited backend
- 26. Allows for easier load-balancing
- 27. Composability Be effective participant in a composed service irrespective of the size and complexity of the composition
- 28. Possibilities include: Direct exposure of one operation within another service
- 29. Routing of messages from one service to another
- 30. Single front-end, selected back-ends depending on operation
- 31. Maintainability & Supportability “Easy” to read contracts
- 32. Ability to fix bugs in service without affecting the contract
- 33. Operational message debugging Understanding the message flow
- 34. Reading the message on the wire might be the only way of identifying an issue
- 35. Goals for Service Contract Design Intrinsic Interoperability
- 36. Business and Technology Alignment
- 38. Federation
- 39. Abstraction
- 40. Reusability
- 41. Composability
- 42. Maintainability
- 43. Supportability
- 44. XML Services
- 45. SOAP vs REST WSDL as contract medium more mature than WADL
- 46. SOAP-based XML Services not restricted to HTTP transports unlike REST
- 47. SOAP-based XML Services has many standards
- 48. Rest of content will concentrate on SOAP-based contracts
- 49. WS-I Profiles Defines requirements for interoperability based upon collections of specific web standards
- 50. Contracts must be designed to conform to a specific profile
- 51. Basic Profile 1.1 / 1.2
- 53. XML Service Guidelines Use XML namespaces to separate data models
- 54. version contracts Prefer SOAP document-literal contracts to rpc-literal Allows data model design to be completely decoupled from service contract in design DO NOT use rpc-encoded contracts
- 55. Four cornerstones Operations What operations are supported? Data model How is the data structured? Locations Where can this service be found? Policies What are the operational policies and contraints?
- 56. Non-functional contract aspects Non-functional aspects are attached to the message header Embedding aspects in message body forces unnecessary coupling Security aspects added via WS-Security policies
- 57. Message routing added via WS-Addressing Required in SOAP 1.2 / Basic Profile 1.2 Reliable messaging added via WS-ReliableMessaging
- 59. Discussion: editNote operation Part name Data type rpc-literal contract
- 60. Discussion: editNote operation What is the meaning of 'Bean'? Why call a returned part 'return'? What is the semantical interpretation of 'edit'? Why call part of a message 'message'?
- 62. XML Message: editNote Use of unnamed namespace
- 63. Discussion: ValidatePackage document-literal contract Message root wrapper element
- 65. XML Message: ValidatePackage Operation is clear; in namespace of contract Re-used data model; in namespace of data model
- 66. Readability: ValidatePackage Correct usage of default namespace – should readability be a problem (positioning of xmlns declarations are implementation-dependent)
- 68. Asynchronous Service Contract Interface implemented by service as per contract Interface to be implemented by consumer in order to receive updates (This is not SOA eventing)
- 69. Asynchronous Routing Header http://www.w3.org/Submission/ws-addressing/
- 71. Asynchronous Reply Header MessageID from request SOAP Action as per contract MessageID from request Endpoint from ReplyTo
- 72. Adding Policy to Service Contract
- 73. Adding Policy to Service Contract Locks down operation only to use one-way channels (anonymous responses across same HTTP channel not allowed) WS-Addressing policy
- 74. Handling large files XML is not optimised for bulk binary data
- 75. Embedding binary data in XML can lead to unnecessary processing overhead in systems.
- 76. Large files should be transferred out-of-band or as attachments.
- 77. MTOM is primary means of adding attachments.
- 78. Out-of-band Transfer Operations Request location & credentials from service, upload, notify on complete
- 79. Provide location & credentials to service
- 80. MTOM in a Nutshell “Message Transfer Optimisation Mechanism” Used in conjunction with “XML-binary Optimised Packaging” (XOP)
- 81. http://www.w3.org/TR/soap12-mtom/ Most modern platforms are MTOM-aware
- 82. Attachments are sent as MIME within same transport channel
- 83. Reference identifier within message body links to attachment
- 85. MTOM on the wire
- 86. Security Aspects in Contracts
- 87. Security Policies Security is a difficult concept for many to grasp
- 88. Creating the infrastructure is not easy
- 89. Start easy with Username Tokens and not encryption + signing
- 90. Move to SAML Tokens when the above is understood
- 91. Add encryption + signing when STS infrastructure is in place
- 92. Read WS-I Basic Security Profile http://www.ws-i.org/Profiles/BasicSecurityProfile-1.1.html
- 93. WS-Security Policy Security policy is attached to contract at an appropriate level
- 95. WS-Security Policy HTTPS required
- 97. WS-Security Policy Authentication is username+password (limited security, SAML tokens are better)
- 99. TDD & Service Contracts How to add testing to a contract without implementing the service
- 100. Using TDD Conventional test-first is very hard and impractical
- 101. Iterative process of designing operation then generating test code
- 102. SoapUI is an efficient tool for TDD of contracts
- 103. Initial tests can be extended to become first set of integration tests
- 104. Initial tests become a living specification
- 105. Helps with documenting the contract
- 106. Test Request Message
- 107. Add Mockservice to Test Response
- 108. Approach Design operation Discuss semantics of names Load WSDL into SoapUI Create Mockservice for response Visual inspection of message Tweak until correct Write tests for service Schema Validation
- 109. Expected content
- 110. Expected header content Next operation Publish to early access Allow other parties access Tweak from feedback Hand tests over for automation
- 111. What makes a Good Contract?
- 112. No implementation technology exposed
- 113. Implementation Technology Can cause unnecessary vendor lock-in for the service implementer Cannot change the back-end without changing the contract Can convey the message that contract has been designed unprofessionally
- 115. Contract-First Design Leads to cleaner interfaces
- 116. Maps better to business requirements Consumer involvement makes the learning and writing process easier. Achieves intrinsic interoperability
- 117. Avoids exposing bugs in the implementation technology and code generators
- 119. Naming Self-explanatory operation names GetCustomerNameByEmailAddress Names in data models must reflect the domain models
- 120. Names should be as simple as possible, but no simpler (“ReplyTo” vs “rt”)
- 121. Names should make it easier to understand the contract
- 122. Element form default is qualified
- 123. Qualified Elements Unambiguous data models
- 124. Unnamed namespaces do not cause issues during message aggregation / splitting
- 125. Accommodates known interoperability issues
- 126. Platform Idiosyncrasy Some technologies have well-known issues
- 127. If known this can be addressed in the contract in a portable manner
- 128. Compromises should affect the contract in a negative way.
- 129. Try out code generators from various platforms and study the artefacts.
- 130. If in doubt, the standards (W3C/Oasis/WS-I) are the law.
- 131. svcutil.exe idiosyncrasy C# Object C# native integer (no limit check) reworked as
- 132. Namespace versioned
- 133. Namespace versioning XML world has two approaches Attribute “version” on root element
- 134. Namespace versioning XML Service world prefers namespace versioning
- 135. Namespace versioning Allows for breaking original structure, but keeping the core of the domain model intact
- 136. Allows mixing content from both versions in a document, but maintaining clear boundaries
- 137. Parsers can be maintained independently
- 138. No data model surprises
- 139. Consistency Specified multiplicity must map to the data model
- 140. If technology does not directly support constraints, implement it in the code
- 141. Ensure test cases cover data model validation
- 143. Non-functional aspects Aspects such as security, routing, eventing and notification decoupled from the data model
- 144. Contained in own schemas
- 145. Attached as policies to the contract
- 146. Allows for various groups to focus on specific dimensions in contract design without being inter-dependant
- 147. Characteristics of Good Contracts No implementation technology exposed
- 150. Qualified elements
- 152. Namespace versioned
- 153. No data model surprises
- 154. Non-functional aspects decoupled from data model
- 155. Wrapping up
- 156. Composability can be easy
- 157. Understand the costs Service contracts are not an afterthought
- 159. Time need to be invested up-front prior to any develop to publish and agree on a suitable interface
- 160. Some tweaking might be required during initial development, but should be clearly communicated to all involved parties via early access program
- 161. Governance Once the contract is published to production it is not allowed to be modifed, only extended
- 162. Modifications require (namespace) versioning, effectively becoming a new contract
- 163. Testing Testers need to understand the domain + the requirements of the various policies
- 164. Must be able to test service direct and interpret XML messages
- 165. Must be able to automate tests that validate the contract using both positive and negative tests
- 166. Schalk W. Cronjé ysb33r @ gmail.com @ysb33r Thank you