|By Steve Close||
|November 20, 2005 04:45 AM EST||
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.
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)
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
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.
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?
|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
|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:
Even for Java Eclipse:
For an in-depth coverage of contract-first design and development with .NET see this article here:
|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.
With so much going on in this space you could be forgiven for thinking you were always working with yesterday’s technologies. So much change, so quickly. What do you do if you have to build a solution from the ground up that is expected to live in the field for at least 5-10 years? This is the challenge we faced when we looked to refresh our existing 10-year-old custom hardware stack to measure the fullness of trash cans and compactors.
Aug. 30, 2016 02:30 AM EDT Reads: 1,851
The emerging Internet of Everything creates tremendous new opportunities for customer engagement and business model innovation. However, enterprises must overcome a number of critical challenges to bring these new solutions to market. In his session at @ThingsExpo, Michael Martin, CTO/CIO at nfrastructure, outlined these key challenges and recommended approaches for overcoming them to achieve speed and agility in the design, development and implementation of Internet of Everything solutions wi...
Aug. 30, 2016 02:00 AM EDT Reads: 2,220
A company’s collection of online systems is like a delicate ecosystem – all components must integrate with and complement each other, and one single malfunction in any of them can bring the entire system to a screeching halt. That’s why, when monitoring and analyzing the health of your online systems, you need a broad arsenal of different tools for your different needs. In addition to a wide-angle lens that provides a snapshot of the overall health of your system, you must also have precise, ...
Aug. 30, 2016 01:45 AM EDT Reads: 1,691
It's been a busy time for tech's ongoing infatuation with containers. Amazon just announced EC2 Container Registry to simply container management. The new Azure container service taps into Microsoft's partnership with Docker and Mesosphere. You know when there's a standard for containers on the table there's money on the table, too. Everyone is talking containers because they reduce a ton of development-related challenges and make it much easier to move across production and testing environm...
Aug. 29, 2016 11:45 PM EDT Reads: 5,261
Aug. 29, 2016 10:45 PM EDT Reads: 4,904
DevOps at Cloud Expo, taking place Nov 1-3, 2016, at the Santa Clara Convention Center in Santa Clara, CA, is co-located with 19th Cloud Expo and will feature technical sessions from a rock star conference faculty and the leading industry players in the world. The widespread success of cloud computing is driving the DevOps revolution in enterprise IT. Now as never before, development teams must communicate and collaborate in a dynamic, 24/7/365 environment. There is no time to wait for long dev...
Aug. 29, 2016 10:00 PM EDT Reads: 2,487
There's a lot of things we do to improve the performance of web and mobile applications. We use caching. We use compression. We offload security (SSL and TLS) to a proxy with greater compute capacity. We apply image optimization and minification to content. We do all that because performance is king. Failure to perform can be, for many businesses, equivalent to an outage with increased abandonment rates and angry customers taking to the Internet to express their extreme displeasure.
Aug. 29, 2016 08:30 PM EDT Reads: 2,438
Monitoring of Docker environments is challenging. Why? Because each container typically runs a single process, has its own environment, utilizes virtual networks, or has various methods of managing storage. Traditional monitoring solutions take metrics from each server and applications they run. These servers and applications running on them are typically very static, with very long uptimes. Docker deployments are different: a set of containers may run many applications, all sharing the resource...
Aug. 29, 2016 08:00 PM EDT Reads: 2,100
Right off the bat, Newman advises that we should "think of microservices as a specific approach for SOA in the same way that XP or Scrum are specific approaches for Agile Software development". These analogies are very interesting because my expectation was that microservices is a pattern. So I might infer that microservices is a set of process techniques as opposed to an architectural approach. Yet in the book, Newman clearly includes some elements of concept model and architecture as well as p...
Aug. 29, 2016 07:30 PM EDT Reads: 10,892
SYS-CON Events announced today that 910Telecom will exhibit at the 19th International Cloud Expo, which will take place on November 1–3, 2016, at the Santa Clara Convention Center in Santa Clara, CA. Housed in the classic Denver Gas & Electric Building, 910 15th St., 910Telecom is a carrier-neutral telecom hotel located in the heart of Denver. Adjacent to CenturyLink, AT&T, and Denver Main, 910Telecom offers connectivity to all major carriers, Internet service providers, Internet backbones and ...
Aug. 29, 2016 07:00 PM EDT Reads: 1,980
This complete kit provides a proven process and customizable documents that will help you evaluate rapid application delivery platforms and select the ideal partner for building mobile and web apps for your organization.
Aug. 29, 2016 06:00 PM EDT Reads: 3,040
DevOps at Cloud Expo – being held November 1-3, 2016, 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 world's largest enterprises – and delivering real results. Am...
Aug. 29, 2016 04:30 PM EDT Reads: 3,568
Modern organizations face great challenges as they embrace innovation and integrate new tools and services. They begin to mature and move away from the complacency of maintaining traditional technologies and systems that only solve individual, siloed problems and work “well enough.” In order to build...
Internet of @ThingsExpo, taking place November 1-3, 2016, at the Santa Clara Convention Center in Santa Clara, CA, is co-located with 19th Cloud Expo and will feature technical sessions from a rock star conference faculty and the leading industry players in the world. The Internet of Things (IoT) is the most profound change in personal and enterprise IT since the creation of the Worldwide Web more than 20 years ago. All major researchers estimate there will be tens of billions devices - comp...
Aug. 29, 2016 02:15 PM EDT Reads: 3,745
[session] Architecting for the Cloud By @RagsS | @CloudExpo @IBMBluemix #Cloud #Docker #Microservices
As the world moves toward more DevOps and Microservices, application deployment to the cloud ought to become a lot simpler. The Microservices architecture, which is the basis of many new age distributed systems such as OpenStack, NetFlix and so on, is at the heart of Cloud Foundry - a complete developer-oriented Platform as a Service (PaaS) that is IaaS agnostic and supports vCloud, OpenStack and AWS. Serverless computing is revolutionizing computing. In his session at 19th Cloud Expo, Raghav...
Aug. 29, 2016 02:00 PM EDT Reads: 1,011
19th Cloud Expo, taking place November 1-3, 2016, at the Santa Clara Convention Center in Santa Clara, CA, will feature technical sessions from a rock star conference faculty and the leading industry players in the world. Cloud computing is now being embraced by a majority of enterprises of all sizes. Yesterday's debate about public vs. private has transformed into the reality of hybrid cloud: a recent survey shows that 74% of enterprises have a hybrid cloud strategy. Meanwhile, 94% of enterpri...
Aug. 29, 2016 12:00 PM EDT Reads: 3,202
The following fictional case study is a composite of actual horror stories I’ve heard over the years. Unfortunately, this scenario often occurs when in-house integration teams take on the complexities of DevOps and ALM integration with an enterprise service bus (ESB) or custom integration. It is written from the perspective of an enterprise architect tasked with leading an organization’s effort to adopt Agile to become more competitive. The company has turned to Scaled Agile Framework (SAFe) as ...
Aug. 29, 2016 12:00 PM EDT Reads: 966
Let's just nip the conflation of these terms in the bud, shall we?
"MIcro" is big these days. Both microservices and microsegmentation are having and will continue to have an impact on data center architecture, but not necessarily for the same reasons. There's a growing trend in which folks - particularly those with a network background - conflate the two and use them to mean the same thing.
They are not.
One is about the application. The other, the network. T...
Aug. 29, 2016 09:30 AM EDT Reads: 4,739
If you are within a stones throw of the DevOps marketplace you have undoubtably noticed the growing trend in Microservices. Whether you have been staying up to date with the latest articles and blogs or you just read the definition for the first time, these 5 Microservices Resources You Need In Your Life will guide you through the ins and outs of Microservices in today’s world.
Aug. 29, 2016 08:30 AM EDT Reads: 5,218
This is a no-hype, pragmatic post about why I think you should consider architecting your next project the way SOA and/or microservices suggest. No matter if it’s a greenfield approach or if you’re in dire need of refactoring. Please note: considering still keeps open the option of not taking that approach. After reading this, you will have a better idea about whether building multiple small components instead of a single, large component makes sense for your project. This post assumes that you...
Aug. 29, 2016 08:15 AM EDT Reads: 5,314