What is in a Good Contract? Designing Interfaces for Distributed Systems Schalk W. Cronjé ysb33r @ gmail.com @ysb33r
Service Contract Decouples service implementation details from clients Allows clients to be developed against standardised...
Contents <ul><li>Goals for service contract design
XML services
Evaluating example contracts
Security policies
TDD & Service Contracts
What makes a good contract? </li></ul>
Goals for Service Contract Design ©  Greco @ skiboardsonline.com
Intrinsic Interoperability which are containing Highly standardised technical contracts Shared common expressions &  data ...
Implementation Technology Agnostic <ul><li>Expression without vendor-specific details
Avoid vendor lock-in within contract
Avoid implementation leakage </li></ul>
Federation Consistent endpoints on technical service portfolio boundary
Business & Technology Alignment <ul><li>Business-centric services
Express business logic in close alignment with business analysis
Production of conceptual versions before physical design </li></ul>
Abstraction <ul><li>Turn service into black box
Contract is the only official published source
Exposure of only essential information </li></ul>
Reusability <ul><li>Ability to re-use service for service composition and routing
Forces decision on granularity of service
Do one thing and do it well </li></ul>
Statelessness <ul><li>Minimise resource consumption
Defer management of state information to a better suited backend
Allows for easier load-balancing </li></ul>
Composability <ul><li>Be effective participant in a composed service irrespective of the size and complexity of the compos...
Possibilities include: </li><ul><li>Direct exposure of one operation within another service
Routing of messages from one service to another
Single front-end, selected back-ends depending on operation </li></ul></ul>
Maintainability & Supportability <ul><li>“Easy” to read contracts
Ability to fix bugs in service without affecting the contract
Operational message debugging </li><ul><li>Understanding the message flow
Reading the message on the wire might be the only way of identifying an issue </li></ul></ul>
Goals for Service Contract Design <ul><li>Intrinsic Interoperability
Business and Technology Alignment
Implementation Technology Agnostic
Federation
Abstraction
Reusability
Composability
Maintainability
Supportability </li></ul>
XML Services
SOAP vs REST <ul><li>WSDL as contract medium more mature than WADL
SOAP-based XML Services not restricted to HTTP transports unlike REST
SOAP-based XML Services has many standards
Rest of content will concentrate on SOAP-based contracts </li></ul>
WS-I Profiles <ul><li>Defines requirements for interoperability based upon collections of specific web standards
Contracts must be designed to conform to a specific profile
Basic Profile 1.1 / 1.2
http://www.ws-i.org </li></ul>
XML Service Guidelines <ul><li>Use XML namespaces to  </li><ul><li>separate data models
version contracts </li></ul><li>Prefer SOAP document-literal contracts to rpc-literal </li><ul><li>Allows data model desig...
Four cornerstones <ul><li>Operations </li><ul><li>What operations are supported? </li></ul><li>Data model </li><ul><li>How...
Non-functional contract aspects <ul><li>Non-functional aspects are attached to the message header </li><ul><li>Embedding a...
Message routing added via WS-Addressing </li><ul><li>Required in SOAP 1.2 / Basic Profile 1.2 </li></ul><li>Reliable messa...
Exploring Contract Examples
Discussion: editNote operation Part name Data type rpc-literal contract
Discussion: editNote operation What is the meaning of 'Bean'? Why call a returned part 'return'? What is the semantical in...
XML Message: editNote
XML Message: editNote Use of unnamed namespace
Discussion: ValidatePackage document-literal contract Message root wrapper element
XML Message: ValidatePackage
XML Message: ValidatePackage Operation is clear; in namespace of contract Re-used data model; in namespace of data model
Readability: ValidatePackage Correct usage of default namespace – should readability be a problem (positioning of xmlns de...
Asynchronous contract
Asynchronous Service Contract Interface implemented by service as per contract Interface to be implemented by consumer in ...
Asynchronous Routing Header http://www.w3.org/Submission/ws-addressing/
Asynchronous Reply Header
Asynchronous Reply Header MessageID from request SOAP Action as per contract MessageID from request Endpoint from ReplyTo
Adding Policy to Service Contract
Adding Policy to Service Contract Locks down operation only to use one-way channels (anonymous responses across same HTTP ...
Handling large files <ul><li>XML is not optimised for bulk binary data
Embedding binary data in XML can lead to unnecessary processing overhead in systems.
Large files should be transferred out-of-band or as attachments.
MTOM is primary means of adding attachments. </li></ul>
Out-of-band Transfer Operations <ul><li>Request location & credentials from service, upload, notify on complete
Provide location & credentials to service </li></ul>
MTOM in a Nutshell <ul><li>“Message Transfer Optimisation Mechanism” </li><ul><li>Used in conjunction with “XML-binary Opt...
Upcoming SlideShare
Loading in...5
×

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

1,850
-1

Published on

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
1,850
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
22
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

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

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

    Clipping is a handy way to collect important slides you want to go back to later.

×