Click here to close now.

Welcome!

Microservices Journal Authors: Roger Strukhoff, Liz McMillan, Elizabeth White, Carmen Gonzalez, Pat Romanski

Related Topics: Microservices Journal

Microservices Journal: Article

Contract-First Web Services: 6 Reasons to Start with WSDL and Schema

"With a little learning, contract-first gets much easier."

I believe that there is a strong tendency for developers to think of Web services as methods. In reality it is not that simple. A Web service defines an XML conversation between client and server. Yet, when a developer sits down to create Web services he or she usually starts by creating a method.

From that starting point it is easy to get a software toolkit to turn your method into a Web service. By default or with a few settings you can allow the toolkit to define the conversation around your method. This method-first development technique works, especially for small or pilot projects, but it is not the best approach. A contract-first approach results in better long-term development, interoperability, and maintenance.

Convincing a development team to work contract-first is not as simple as it might seem. You have to convince the team to spend more effort on unfamiliar languages like XML Schema and WSDL, and rely less on familiar languages such as Java or C#. With that said, there are good reasons to code your Web service the hard way - contract-first. In this article we will look at six good reasons to develop Web services contract-first instead of method-first. By the end of this article I hope you will see that contract-first is a superior way to create Web services and will save you time and money.

RPC Thinking
Before we delve into the six reasons, I want to establish the difference between method-first and contract-first Web services. We can walk through the basic steps of both styles of Web services creation using a simple service. This will allow me to show some code and remove the abstractness from the topic. Forgive me for using an example that has been repeated countless times. If you're an old pro at Web services skip ahead to the "Reason 1" heading. The following code is a Calculator with one method. My preferred weapons are Java and Apache Axis, so all examples will be coded in Java. Your choice of language or platform should have little effect on which way you will make Web services. (see Figure 1)

Step1: Create a method that will become a Web service. The code below provides simple add method that will be turned into a Web service.

public int add(op1, op2)
{
    return op1 + op2;
}

Step 2: Run this method through a software toolkit that turns it into a Web service. There are many of these toolkits on the market. It might be as simple as adding an attribute, or saving the source code to a different extension. For the rest of this article we will call that machine the Web service toolkit. (see Figure 2)

Step 3: Deploy it to some Web server. The server will provide HTTP handling and leave you with a very simple Web service. Web service toolkits automatically create XML conversion code and a Web service description or WSDL (pronounced wizdle) document. This WSDL document is the key to getting a client to call your Web service and will play a prominent roll in contract-first thinking.

Step 4: A client can now obtain the WSDL document and create a client through your Web service. The cool thing is that the client can basically treat the Web service like a regular method call. Although XML is being passed via HTTP following the rules of SOAP, the client can be created very easily and the client doesn't need to know about the XML payload. (see Figure 3)

Contract-First Thinking
Taking a quick look at contract-first development, we can clearly see the differences between method-first and contract-first. In contract-first Web services you first create the WSDL document. The WSDL might have supporting XML Schema documents as well. As you can see from Listing 1, the WSDL code is a bit longer and more involved than the simple Java method. In fact, when you look at it in such a simple example, it almost seems ridiculous to suggest that you might write the WSDL before you write the Java code, but that is exactly what I'm suggesting. The steps to create the Web service are similar to what we've already seen, but kind of in reverse.

  • Step 1: Create the WSDL and supporting Schema
  • Step 2: Generate the service from the WSDL
It seems my work is cut out for me. The first way seems so much easier at first glance, and for small applications and for learning Web services it is the right way. For larger applications, long-lasting Web services, and service-oriented architecture (SOA), contract-first thinking has advantages that usually outweigh the ease of method-first thinking. The rest of this article we will investigate the six reasons to develop contract-first.

Reason 1: Schema Is More Descriptive
Data types in Java and C# and other languages are described only in code, which is not shared with the client. Clients are generated via the WSDL document. Clients don't have the full definition of the data types unless you include that information in the XML Schema document. As a very simple example, say you are passing in a Person that consists of a firstName, middleInitial, and a lastName. In code this is simple, but some of the data may not be required. Say you want to require the firstName and lastName, but the middle initial is optional. If your WSDL is automatically generated, it is likely to turn out like Listing 2. The middleInitial is created by default, but with the XML Schema language we can get much more descriptive. With this simple example we can easily make the middleInitial optional by including one little attribute called minOccurs like the code below.

<xs:element name="middleInitial"
minOccurs="0" type="xs:string" />

I hope this simple example illustrates how schema can be more descriptive, but it is such a tiny example. Imagine a rich set of data, not just a simple person. If you want your clients to understand that the quantity element can only be non-negative integers, or have them understand the pattern that the SKU number must be three letters followed by a hyphen and four numbers, that can be described in XML Schema. By relying on the tool to generate the proper schema, you are passing only a vague description of the data where an e-mail address becomes a string and a month is an integer that can be negative.

Knowing that the WSDL is your client's interface it should be obvious that you want to make it as accurate and descriptive as possible. That might not be enough to write the WSDL first. You could still modify the WSDL after the fact and pass that out to your clients, but we have more reasons to go.

Reason 2: Your Language Is Not Alone
To understand the "we are not alone" idea, we only need to expand the Web service example a bit. You create a Web service and you require that data representing a customer be sent to invoke the service. You may have put some time into the customer type and you realize it should be shared. Other departments also use the same entity in their services, but wait, here's the problem. You code in C#, they code in Java. You can't just centralize the code. They need to convert it to Java. No big deal, as easily done as said practically, but what if the definition of a customer changes? If the Java coders change the customer your two versions no longer match. Which version is the "central" or "master" customer type? Do I need to change the Java code every time I change the C#? How do you communicate the change to the other team?

More Stories By Steve Close

Steve Close is the lead Java instructor for Intertech Training (www.intertechtraining.com). He helped found the Twin Cities Java User Group and served as president from 1997-2000. He has authored many popular workshops for Intertech Training on topics ranging from Java 101 to J2EE, and Java Web services. He has presented at JavaOne, SDWest, and No Fluff Just Stuff. He currently focuses his work on Java, XML, and Web services course development and training.

Comments (4) View Comments

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.


Most Recent Comments
Jeff Kessler 12/13/05 05:32:16 PM EST

What would be a good followup to this article would be a short tutorial on WSDL first development.

Agree 11/20/05 04:52:20 AM EST

>> Contract-first makes following standards easier
>> because all of the standards are written for the
>> WSDL description and SOAP message.

Yes, yes.

Christian Weyer 11/07/05 12:34:29 PM EST

There is free tool support for building your WSDL without having to know all those insane details:
http://www.thinktecture.com/Resources/Software/WSContractFirst/default.html

Even for Java Eclipse:
http://blogs.thinktecture.com/cweyer/archive/2005/08/06/414103.aspx

For an in-depth coverage of contract-first design and development with .NET see this article here:
http://www.code-magazine.com/Article.aspx?quickid=0507061

Patrick Rooney 10/26/05 05:38:04 PM EDT

Excellent article Steve! The approach of focusing on the data to ensure consistency and re-use of services across the enterprise is very important, and not well understood by many developers. In our implementation of SOA across IBM we are using a similar approach. We have defined our own "Enterprise Integration Messaging Specification", which is based on the OAGIS (8.0) XML Schema messaging standard, to establish re-usable message payload structural and data dictionary schema types that can be re-used across the enterprise. These are used to define the parameters (data schema types) that are sent in the messages (Service Operation parameters). The wsdl is created and from these the Services are created.

@MicroservicesExpo Stories
SYS-CON Events announced today that B2Cloud, a provider of enterprise resource planning software, will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. B2cloud develops the software you need. They have the ideal tools to help you work with your clients. B2Cloud’s main solutions include AGIS – ERP, CLOHC, AGIS – Invoice, and IZUM
SYS-CON Events announced today that Tufin, the market-leading provider of Security Policy Orchestration Solutions, will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. As the market leader of Security Policy Orchestration, Tufin automates and accelerates network configuration changes while maintaining security and compliance. Tufin's award-winning Orchestration Suite™ gives IT organizations the power and a...
SYS-CON Events announced today that Cloudian, Inc., the leading provider of hybrid cloud storage solutions, will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. Cloudian, Inc., is a Foster City, California - based software company specializing in cloud storage software. The main product is Cloudian, an Amazon S3-compliant cloud object storage platform, the bedrock of cloud computing systems, that enables c...
SYS-CON Events announced today the IoT Bootcamp – Jumpstart Your IoT Strategy, being held June 9–10, 2015, in conjunction with 16th Cloud Expo and Internet of @ThingsExpo at the Javits Center in New York City. This is your chance to jumpstart your IoT strategy. Combined with real-world scenarios and use cases, the IoT Bootcamp is not just based on presentations but includes hands-on demos and walkthroughs. We will introduce you to a variety of Do-It-Yourself IoT platforms including Arduino, Ras...
SYS-CON Events announced today the DevOps Foundation Certification Course, being held June ?, 2015, in conjunction with DevOps Summit and 16th Cloud Expo at the Javits Center in New York City, NY. This sixteen (16) hour course provides an introduction to DevOps – the cultural and professional movement that stresses communication, collaboration, integration and automation in order to improve the flow of work between software developers and IT operations professionals. Improved workflows will res...
SYS-CON Events announced today that Soha will exhibit at SYS-CON's DevOps Summit New York, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. Soha delivers enterprise-grade application security, on any device, as agile as the cloud. This turnkey, cloud-based service enables customers to solve secure application access and delivery challenges that traditional or virtualized network solutions cannot solve because they are too expensive, inflexible and operational...
SYS-CON Events announced today that Ciqada will exhibit at SYS-CON's @ThingsExpo, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. Ciqada™ makes it easy to connect your products to the Internet. By integrating key components - hardware, servers, dashboards, and mobile apps - into an easy-to-use, configurable system, your products can quickly and securely join the internet of things. With remote monitoring, control, and alert messaging capability, you will mee...
Containers and microservices have become topics of intense interest throughout the cloud developer and enterprise IT communities. Accordingly, attendees at the upcoming 16th Cloud Expo at the Javits Center in New York June 9-11 will find fresh new content in a new track called PaaS | Containers & Microservices Containers are not being considered for the first time by the cloud community, but a current era of re-consideration has pushed them to the top of the cloud agenda. With the launch ...
of cloud, colocation, managed services and disaster recovery solutions, will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. TierPoint, LLC, is a leading national provider of information technology and data center services, including cloud, colocation, disaster recovery and managed IT services, with corporate headquarters in St. Louis, MO. TierPoint was formed through the strategic combination of some of t...
Public Cloud IaaS started it's life in the developer and startup communities and has grown rapidly to a $20B+ industry, but it still pales in comparison to how much is spent worldwide on IT: $3.6 trillion. In fact, there are 8.6 million data centers worldwide, the reality is many small and medium sized business have server closets and colocation footprints filled with servers and storage gear. While on-premise environment virtualization may have peaked at 75%, the Public Cloud has lagged in ado...
Dave will share his insights on how Internet of Things for Enterprises are transforming and making more productive and efficient operations and maintenance (O&M) procedures in the cleantech industry and beyond. Speaker Bio: Dave Landa is chief operating officer of Cybozu Corp (kintone US). Based in the San Francisco Bay Area, Dave has been on the forefront of the Cloud revolution driving strategic business development on the executive teams of multiple leading Software as a Services (SaaS) ap...
Microsoft is releasing in the near future Azure Service Fabric as a preview beta. Azure Service Fabric is built to run microservices - a complex application consisting of smaller, interlocked components that enables updating components without disrupting service. Microsoft has used this over the past few years internally for many of its own applications and the new release is for general use, a new product. OSIsoft is an early adopter of this system and run with it to expand into the explo...
ProfitBricks, the provider of painless cloud infrastructure IaaS, today released its SDK for Ruby, written against the company's new RESTful API. The new SDK joins ProfitBricks' previously announced support for the popular multi-cloud open-source Fog project. This new Ruby SDK, which exposes advanced functionality to take advantage of ProfitBricks' simplicity and productivity, aligns with ProfitBricks' mission to provide a painless way to automate infrastructure in the cloud. Ruby is a genera...
ProfitBricks, the provider of painless cloud infrastructure for IaaS, today announced the release of a Node.js SDK written against its recently launched REST API. This new JavaScript based library provides coverage for all existing ProfitBricks REST API functions. With additional libraries set to release this month, ProfitBricks continues to prove its dedication to the DevOps community and commitment to making cloud migrations and cloud management painless. Node.js is an open source, cross-pl...
ProfitBricks, the provider of painless cloud infrastructure IaaS, announced the launch of its new DevOps Central and REST API, along with support for three multi-cloud libraries and a Python SDK. This, combined with its already existing SOAP API and its new RESTful API, moves ProfitBricks into a position to better serve the DevOps community and provide the ability to automate cloud infrastructure in a multi-cloud world. Following this momentum, ProfitBricks is also today introducing several l...
What exactly is a cognitive application? In her session at 16th Cloud Expo, Ashley Hathaway, Product Manager at IBM Watson, will look at the services being offered by the IBM Watson Developer Cloud and what that means for developers and Big Data. She'll explore how IBM Watson and its partnerships will continue to grow and help define what it means to be a cognitive service, as well as take a look at the offerings on Bluemix. She will also check out how Watson and the Alchemy API team up to off...
The 17th International Cloud Expo has announced that its Call for Papers is open. 17th International Cloud Expo, to be held November 3-5, 2015, at the Santa Clara Convention Center in Santa Clara, CA, brings together Cloud Computing, APM, APIs, Microservices, Security, Big Data, Internet of Things, DevOps and WebRTC to one location. With cloud computing driving a higher percentage of enterprise IT budgets every year, it becomes increasingly important to plant your flag in this fast-expanding bu...
The 5th International DevOps Summit, co-located with 17th International Cloud Expo – being held November 3-5, 2015, at the Santa Clara Convention Center in Santa Clara, CA – announces that its Call for Papers is open. Born out of proven success in agile development, cloud computing, and process automation, DevOps is a macro trend you cannot afford to miss. From showcase success stories from early adopters and web-scale businesses, DevOps is expanding to organizations of all sizes, including the...
So I guess we’ve officially entered a new era of lean and mean. I say this with the announcement of Ubuntu Snappy Core, “designed for lightweight cloud container hosts running Docker and for smart devices,” according to Canonical. “Snappy Ubuntu Core is the smallest Ubuntu available, designed for security and efficiency in devices or on the cloud.” This first version of Snappy Ubuntu Core features secure app containment and Docker 1.6 (1.5 in main release), is available on public clouds, ...
There is no quick way to learn Jython API but to experiment with it. The easiest way is to start with Jytutor extension for XL Deploy. Now you can also use the code snippet for exposing jython/python context in XL Deploy environment by running it directly in Jytutor Here’s how you can go ahead with that Download the Jytutor extension referring to the Jytutor Blog or from the following link https://github.com/xebialabs-community/xld-jytutor-plugin/releases Shutdown your XL Deploy server...