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

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

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

1,670

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,670
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
22
Comments
0
Likes
0
Embeds 0
No embeds

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

×