{"id":508,"date":"2010-09-01T07:53:10","date_gmt":"2010-09-01T05:53:10","guid":{"rendered":"http:\/\/www.pleus.net\/blog\/?p=508"},"modified":"2011-06-01T08:36:50","modified_gmt":"2011-06-01T06:36:50","slug":"schema-first-contract-design","status":"publish","type":"post","link":"https:\/\/www.pleus.net\/blog\/?p=508","title":{"rendered":"Schema first contract design"},"content":{"rendered":"

One of the most important artifacts in Service-oriented Architecture (SOA) is the service contract. The contract defines how service producers and consumers interact with each other. Most people agree that a contract first approach is the preferred way of creating service contracts. WSDL based service contracts are very common. In many projects they are generated by the respective frameworks, such as Apache CXF or Microsoft WCF. This is dangerous, as the developer looses control over the contract. This can result in missing interoperability and limited reusabilty expecially in cross platform scenarios.
\nFrom what I see, most developers know how to work with their favourite IDE, but only a few know how to create a proper service contract from scratch. I think that is caused by the tool vendors, which in most cases have better support for code based approaches.
\nIn this post\u00a0I would like to show how to create a portable contract from scratch and share some best practices.<\/p>\n

The domain model<\/strong><\/p>\n

The first thing to think about is the domain or entity model that the service should expose. The model\u00a0should be\u00a0modeled in XML Schema. XML Schema is standard, portable and supported on all platforms. In fact it is a good idea to use\u00a0XML Schema as the\u00a0single source\u00a0of model information.<\/p>\n

The following listing defines the entity Product:
\n\u00a0<\/p>\n

\r\n\r\n  \r\n    \r\n      \r\n        \r\n          Name of the product<\/xs:documentation>\r\n        <\/xs:annotation>\r\n      <\/xs:element>\r\n      \r\n        \r\n          Quantity on stock<\/xs:documentation>\r\n        <\/xs:annotation>\r\n      <\/xs:element>\r\n    <\/xs:sequence>\r\n  <\/xs:complexType>\r\n<\/xs:schema><\/pre>\n
The entity Product has two attributes name and quantity. Please note that the xml elements (line 10 and 15) are abbreviated. This helps to reduce the message size on the wire, expecially important in WANs. The downside is obviously reduced readability. That is not really a problem as the contract should be documented anyway using the standard XML Schema annotation elements as shown in line 11 to 13.
\nThis is the result:
\n\"\"<\/a><\/p>\n
Wouldn’t it be nice to have a common base class in order to create a more generic service contract?
\nLuckily XML Schema allows that. Let’s create another schema BaseTypes.xsd<\/em> in which we define the base types.<\/p>\n
\r\n\r\n  \r\n    \r\n      \r\n      \r\n    <\/xs:restriction>\r\n  <\/xs:simpleType>\r\n\r\n  \r\n    \r\n      \r\n      \r\n      \r\n      \r\n    <\/xs:restriction>\r\n  <\/xs:simpleType>\r\n\r\n  \r\n    \r\n      \r\n        \r\n          Unique key<\/xs:documentation>\r\n        <\/xs:annotation>\r\n      <\/xs:element>\r\n      \r\n        \r\n          Status of the entity<\/xs:documentation>\r\n        <\/xs:annotation>\r\n      <\/xs:element>\r\n    <\/xs:sequence>\r\n  <\/xs:complexType>\r\n<\/xs:schema><\/pre>\n
This base type Entity <\/em>(line 24) defines common attributes for all entities. In XML Schema one can define enumerations as well (line 8 and 15). The enumeration EntityStatus<\/em> defines the state of the entity. This is important in scenarios in which the entities are detached from the database. By marking the entities, it is easy to implement change tracking on the consumer side and just return the changed or deleted parts to the server. This saves network and processing time. EntityType<\/em> is used later in our service interface to request different types of entities.
\nWe can now import the base types into Types.xsd<\/em> and change the Product type:<\/p>\n
\r\n\r\n\r\n\r\n  \r\n    \r\n      \r\n        \r\n          \r\n            \r\n              Name of the product<\/xs:documentation>\r\n            <\/xs:annotation>\r\n          <\/xs:element>\r\n          \r\n            \r\n              Quantity on stock<\/xs:documentation>\r\n            <\/xs:annotation>\r\n          <\/xs:element>\r\n        <\/xs:sequence>\r\n      <\/xs:extension>\r\n    <\/xs:complexContent>\r\n  <\/xs:complexType>\r\n<\/xs:schema>\r\n<\/pre>\n
You can see the import in line 9. In line 12 and 13 the base type is added to the Product type.<\/p>\n
Now we have our model completely defined in XML Schema. By using imports and type inheritance one can create very modular entity models. Those models can be reused without any change by interface definitions such as WSDL and WADL for SOAP or REST services. Moreover the code models (Java, C#, etc.) can be fully generated from the schema. Every good framework has a generator tool on board. For instance Apache Axis\/wsdl2java, Apache CXF\/wsd2java, Silverlight\/slsvcutil, .NET\/svcutil, etc. The schema can be stored in a service repository in order to increase reusability amongst the organisation.<\/p>\n
The messages<\/strong>
\nEvery service operation receives a message and returns a message to the sender. Those messages should also be defined using XML Schema. The following snippet shows the message definitions. The fault messages are ommitted for the sake of simplification.<\/p>\n
\r\n    \r\n      \r\n    <\/xs:sequence>\r\n  <\/xs:complexType>\r\n\r\n  \r\n    \r\n      \r\n    <\/xs:sequence>\r\n  <\/xs:complexType>\r\n\r\n    \r\n        \r\n            This represents a request to read business entities<\/xs:documentation>\r\n        <\/xs:annotation>\r\n        \r\n            \r\n                \r\n                    \r\n                        Type of the entities to read<\/xs:documentation>\r\n                    <\/xs:annotation>\r\n                <\/xs:element>\r\n                \r\n                    \r\n                        Unique keys of the entities to read<\/xs:documentation>\r\n                    <\/xs:annotation>\r\n                <\/xs:element>\r\n            <\/xs:sequence>\r\n        <\/xs:complexType>\r\n    <\/xs:element>\r\n\r\n    \r\n        \r\n            This represents the read response<\/xs:documentation>\r\n        <\/xs:annotation>\r\n        \r\n            \r\n                \r\n                    \r\n                        List of entities<\/xs:documentation>\r\n                    <\/xs:annotation>\r\n                <\/xs:element>\r\n            <\/xs:sequence>\r\n        <\/xs:complexType>\r\n    <\/xs:element>\r\n<\/pre>\n
ReadEntitiesRequest<\/em> and ReadEntitiesResponse<\/em> are bulk operations that allow to read multiple entities with one call. As you can see ReadEntitiesResponse<\/em> does not return Products but Entities. Do you remember? This is our base class type for all entities. By using the base class, the message can return arbitrary entity types in the same message. This is an example for a strongly typed but yet extensible interface.<\/p>\n
The schemas can be reused in WSDL files:<\/p>\n
\r\n\r\n  \r\n  \r\n  \r\n  \r\n      \r\n  <\/wsdl:message>\r\n  \r\n    \r\n  <\/wsdl:message>\r\n  \r\n  \r\n    \r\n      \r\n      \r\n    <\/wsdl:operation>\r\n  <\/wsdl:portType>\r\n\r\n  \r\n        \r\n    \r\n      \r\n      \r\n        \r\n      <\/wsdl:input>\r\n      \r\n        \r\n      <\/wsdl:output>\r\n    <\/wsdl:operation>\r\n  <\/wsdl:binding>\r\n  \r\n    \r\n      \r\n    <\/wsdl:port>\r\n  <\/wsdl:service>\r\n<\/wsdl:definitions>\r\n<\/pre>\n
The type information and message definitions are completely externalized to individual schemas. As a result the WSDL is small. The imported types (line 4) are used to define the WSDL messages (line 7 and 10). A WADL file would look like this:<\/p>\n
\r\n\r\n  \r\n    \r\n    \r\n  <\/grammars>\r\n\r\n  \r\n    \r\n      \r\n        \r\n<\/span>\r\n            \r\n              \r\n                This is the product id\r\n              <\/xsi:documentation>\r\n            <\/xsi:annotation>\r\n          <\/param>\r\n        <\/request>\r\n        \r\n          \r\n        <\/response>\r\n      <\/method>\r\n    <\/resource>\r\n  <\/resources>\r\n<\/application>\r\n<\/pre>\n
The types are imported (line 8 and 9) and used to define the return message (25).
\nBy using the respective tool, such as wsdl2java or svcutil, we can completely generate the model and messages for the client and server on JEE, .NET and other platforms.<\/p>\n
Summary<\/strong>
\nAs you can see it is not too difficult to create schema based service contracts in a platform agnostic way. If you do, you will be rewarded with a great level of control, portability and reusability. Powerful features of XML Schema, such as inheritance, allow to create robust and extensible service contracts, which are the basis for interoperability. And if you want, you can even use an XML editor. \ud83d\ude09<\/p>\n","protected":false},"excerpt":{"rendered":"
One of the most important artifacts in Service-oriented Architecture (SOA) is the service contract. The contract defines how service producers and consumers interact with each other. Most people agree that a contract first approach is the preferred way of creating service contracts. WSDL based service contracts are very common. In many projects they are generated … Continue reading Schema first contract design<\/span><\/a><\/p>\n","protected":false},"author":3,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[3],"tags":[28,77,29,27,26,25],"class_list":["post-508","post","type-post","status-publish","format-standard","hentry","category-soa","tag-rest","tag-soa","tag-soap","tag-wadl","tag-wsdl","tag-xml"],"_links":{"self":[{"href":"https:\/\/www.pleus.net\/blog\/index.php?rest_route=\/wp\/v2\/posts\/508","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.pleus.net\/blog\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.pleus.net\/blog\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.pleus.net\/blog\/index.php?rest_route=\/wp\/v2\/users\/3"}],"replies":[{"embeddable":true,"href":"https:\/\/www.pleus.net\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=508"}],"version-history":[{"count":109,"href":"https:\/\/www.pleus.net\/blog\/index.php?rest_route=\/wp\/v2\/posts\/508\/revisions"}],"predecessor-version":[{"id":768,"href":"https:\/\/www.pleus.net\/blog\/index.php?rest_route=\/wp\/v2\/posts\/508\/revisions\/768"}],"wp:attachment":[{"href":"https:\/\/www.pleus.net\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=508"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.pleus.net\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=508"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.pleus.net\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=508"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
Those are our messages:
\n\"\"<\/a>
\n\"\"<\/a><\/p>\n
This is the result:
\n\"Entity<\/a><\/p>\n