Click here to close now.




















Welcome!

Microservices Expo Authors: Lori MacVittie, Trevor Parsons, Mike Kavis, Liz McMillan, Tom Lounibos

Related Topics: Microservices Expo

Microservices Expo: 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
At DevOps Summit NY there’s been a whole lot of talk about not just DevOps, but containers, IoT, and microservices. Sessions focused not just on the cultural shift needed to grow at scale with a DevOps approach, but also made sure to include the network ”plumbing” needed to ensure success as applications decompose into the microservice architectures enabling rapid growth and support for the Internet of (Every)Things.
Auto-scaling environments, micro-service architectures and globally-distributed teams are just three common examples of why organizations today need automation and interoperability more than ever. But is interoperability something we simply start doing, or does it require a reexamination of our processes? And can we really improve our processes without first making interoperability a requirement for how we choose our tools?
Our guest on the podcast this week is Adrian Cockcroft, Technology Fellow at Battery Ventures. We discuss what makes Docker and Netflix highly successful, especially through their use of well-designed IT architecture and DevOps.
Explosive growth in connected devices. Enormous amounts of data for collection and analysis. Critical use of data for split-second decision making and actionable information. All three are factors in making the Internet of Things a reality. Yet, any one factor would have an IT organization pondering its infrastructure strategy. How should your organization enhance its IT framework to enable an Internet of Things implementation? In his session at @ThingsExpo, James Kirkland, Red Hat's Chief Arch...
This week, I joined SOASTA as Senior Vice President of Performance Analytics. Given my background in cloud computing and distributed systems operations — you may have read my blogs on CNET or GigaOm — this may surprise you, but I want to explain why this is the perfect time to take on this opportunity with this team. In fact, that’s probably the best way to break this down. To explain why I’d leave the world of infrastructure and code for the world of data and analytics, let’s explore the timing...
Digital Transformation is the ultimate goal of cloud computing and related initiatives. The phrase is certainly not a precise one, and as subject to hand-waving and distortion as any high-falutin' terminology in the world of information technology. Yet it is an excellent choice of words to describe what enterprise IT—and by extension, organizations in general—should be working to achieve. Digital Transformation means: handling all the data types being found and created in the organizat...
Alibaba, the world’s largest ecommerce provider, has pumped over a $1 billion into its subsidiary, Aliya, a cloud services provider. This is perhaps one of the biggest moments in the global Cloud Wars that signals the entry of China into the main arena. Here is why this matters. The cloud industry worldwide is being propelled into fast growth by tremendous demand for cloud computing services. Cloud, which is highly scalable and offers low investment and high computational capabilities to end us...
Public Cloud IaaS started its 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 adop...
SYS-CON Events announced today that HPM Networks will exhibit at the 17th International Cloud Expo®, which will take place on November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. For 20 years, HPM Networks has been integrating technology solutions that solve complex business challenges. HPM Networks has designed solutions for both SMB and enterprise customers throughout the San Francisco Bay Area.
The Software Defined Data Center (SDDC), which enables organizations to seamlessly run in a hybrid cloud model (public + private cloud), is here to stay. IDC estimates that the software-defined networking market will be valued at $3.7 billion by 2016. Security is a key component and benefit of the SDDC, and offers an opportunity to build security 'from the ground up' and weave it into the environment from day one. In his session at 16th Cloud Expo, Reuven Harrison, CTO and Co-Founder of Tufin,...
MuleSoft has announced the findings of its 2015 Connectivity Benchmark Report on the adoption and business impact of APIs. The findings suggest traditional businesses are quickly evolving into "composable enterprises" built out of hundreds of connected software services, applications and devices. Most are embracing the Internet of Things (IoT) and microservices technologies like Docker. A majority are integrating wearables, like smart watches, and more than half plan to generate revenue with ...
JavaScript is primarily a client-based dynamic scripting language most commonly used within web browsers as client-side scripts to interact with the user, browser, and communicate asynchronously to servers. If you have been part of any web-based development, odds are you have worked with JavaScript in one form or another. In this article, I'll focus on the aspects of JavaScript that are relevant within the Node.js environment.
One of the ways to increase scalability of services – and applications – is to go “stateless.” The reasons for this are many, but in general by eliminating the mapping between a single client and a single app or service instance you eliminate the need for resources to manage state in the app (overhead) and improve the distributability (I can make up words if I want) of requests across a pool of instances. The latter occurs because sessions don’t need to hang out and consume resources that could ...
Rapid innovation, changing business landscapes, and new IT demands force businesses to make changes quickly. The DevOps approach is a way to increase business agility through collaboration, communication, and integration across different teams in the IT organization. In his session at DevOps Summit, Chris Van Tuin, Chief Technologist for the Western US at Red Hat, will discuss: The acceleration of application delivery for the business with DevOps
Growth hacking is common for startups to make unheard-of progress in building their business. Career Hacks can help Geek Girls and those who support them (yes, that's you too, Dad!) to excel in this typically male-dominated world. Get ready to learn the facts: Is there a bias against women in the tech / developer communities? Why are women 50% of the workforce, but hold only 24% of the STEM or IT positions? Some beginnings of what to do about it! In her Opening Keynote at 16th Cloud Expo, S...
Software is eating the world. The more it eats, the bigger the mountain of data and wealth of valuable insights to digest and act on. Forward facing customer-centric IT organizations, leaders and professionals are looking to answer questions like how much revenue was lost today from platinum users not converting because they experienced poor mobile app performance. This requires a single, real-time pane of glass for end-to-end analytics covering business, customer, and IT operational data.
Approved this February by the Internet Engineering Task Force (IETF), HTTP/2 is the first major update to HTTP since 1999, when HTTP/1.1 was standardized. Designed with performance in mind, one of the biggest goals of HTTP/2 implementation is to decrease latency while maintaining a high-level compatibility with HTTP/1.1. Though not all testing activities will be impacted by the new protocol, it's important for testers to be aware of any changes moving forward.
"ProfitBricks was founded in 2010 and we are the painless cloud - and we are also the Infrastructure as a Service 2.0 company," noted Achim Weiss, Chief Executive Officer and Co-Founder of ProfitBricks, in this SYS-CON.tv interview at 16th Cloud Expo, held June 9-11, 2015, at the Javits Center in New York City.
You often hear the two titles of "DevOps" and "Immutable Infrastructure" used independently. In his session at DevOps Summit, John Willis, Technical Evangelist for Docker, covered the union between the two topics and why this is important. He provided an overview of Immutable Infrastructure then showed how an Immutable Continuous Delivery pipeline can be applied as a best practice for "DevOps." He ended the session with some interesting case study examples.
The Internet of Things. Cloud. Big Data. Real-Time Analytics. To those who do not quite understand what these phrases mean (and let’s be honest, that’s likely to be a large portion of the world), words like “IoT” and “Big Data” are just buzzwords. The truth is, the Internet of Things encompasses much more than jargon and predictions of connected devices. According to Parker Trewin, Senior Director of Content and Communications of Aria Systems, “IoT is big news because it ups the ante: Reach out ...