What is in a Good Contract? Designing Interfaces for Distributed Systems
Upcoming SlideShare
Loading in...5
×

Like this? Share it with your network

Share

What is in a Good Contract? Designing Interfaces for Distributed Systems

  • 2,059 views
Uploaded on

 

More in: Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads

Views

Total Views
2,059
On Slideshare
2,058
From Embeds
1
Number of Embeds
1

Actions

Shares
Downloads
19
Comments
0
Likes
0

Embeds 1

http://www.linkedin.com 1

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 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
    • 5. Evaluating example contracts
    • 6. Security policies
    • 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
    • 13. Avoid implementation leakage
  • 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
    • 37. Implementation Technology Agnostic
    • 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
    • 52. http://www.ws-i.org
  • 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
  • 58. Exploring Contract Examples
  • 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'?
  • 61. XML Message: editNote
  • 62. XML Message: editNote Use of unnamed namespace
  • 63. Discussion: ValidatePackage document-literal contract Message root wrapper element
  • 64. XML Message: ValidatePackage
  • 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)
  • 67. Asynchronous contract
  • 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/
  • 70. Asynchronous Reply Header
  • 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
  • 84. MTOM Type Declaration
  • 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
  • 94. WS-Security Policy
  • 95. WS-Security Policy HTTPS required
  • 96. WS-Security Policy
  • 97. WS-Security Policy Authentication is username+password (limited security, SAML tokens are better)
  • 98. WS-Security Policy
  • 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
  • 114. Contract-first design
  • 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
  • 118. Intuitive, business-centric names
  • 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
  • 142. Non-functional aspects decoupled
  • 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
    • 148. Contract-first design
    • 149. Intuitive, business-centric names
    • 150. Qualified elements
    • 151. Interoperability issues accommodated
    • 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
    • 158. Use contract-first design
    • 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