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

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

12. Avoid vendor lock-in within contract

13. Avoid implementation leakage

14. Federation Consistent endpoints on technical service portfolio boundary

16. Express business logic in close alignment with business analysis

17. Production of conceptual versions before physical design

19. Contract is the only official published source

20. Exposure of only essential information

22. Forces decision on granularity of service

23. Do one thing and do it well

25. Defer management of state information to a better suited backend

26. Allows for easier load-balancing

29. Routing of messages from one service to another

30. Single front-end, selected back-ends depending on operation

32. Ability to fix bugs in service without affecting the contract

34. Reading the message on the wire might be the only way of identifying an issue

36. Business and Technology Alignment

37. Implementation Technology Agnostic

38. Federation

39. Abstraction

40. Reusability

41. Composability

42. Maintainability

43. Supportability

44. XML Services

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

50. Contracts must be designed to conform to a specific profile

51. Basic Profile 1.1 / 1.2

52. http://www.ws-i.org

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

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.

79. Provide location & credentials to service

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

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

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

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

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

114. Contract-first design

117. Avoids exposing bugs in the implementation technology and code generators

118. Intuitive, business-centric names

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

124. Unnamed namespaces do not cause issues during message aggregation / splitting

125. Accommodates known interoperability 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

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

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

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

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

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

162. Modifications require (namespace) versioning, effectively becoming a new contract

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