|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.
In the world of DevOps there are ‘known good practices’ – aka ‘patterns’ – and ‘known bad practices’ – aka ‘anti-patterns.' Many of these patterns and anti-patterns have been developed from real world experience, especially by the early adopters of DevOps theory; but many are more feasible in theory than in practice, especially for more recent entrants to the DevOps scene. In this power panel at @DevOpsSummit at 18th Cloud Expo, moderated by DevOps Conference Chair Andi Mann, panelists discusse...
Jul. 1, 2016 04:45 PM EDT Reads: 1,083
When people aren’t talking about VMs and containers, they’re talking about serverless architecture. Serverless is about no maintenance. It means you are not worried about low-level infrastructural and operational details. An event-driven serverless platform is a great use case for IoT. In his session at @ThingsExpo, Animesh Singh, an STSM and Lead for IBM Cloud Platform and Infrastructure, will detail how to build a distributed serverless, polyglot, microservices framework using open source tec...
Jul. 1, 2016 08:30 AM EDT Reads: 810
Cloud Expo, Inc. has announced today that Andi Mann returns to 'DevOps at Cloud Expo 2016' as Conference Chair The @DevOpsSummit at Cloud Expo will take place on November 1-3, 2016, at the Santa Clara Convention Center in Santa Clara, CA. "DevOps is set to be one of the most profound disruptions to hit IT in decades," said Andi Mann. "It is a natural extension of cloud computing, and I have seen both firsthand and in independent research the fantastic results DevOps delivers. So I am excited t...
Jul. 1, 2016 12:00 AM EDT Reads: 638
More and more companies are looking to microservices as an architectural pattern for breaking apart applications into more manageable pieces so that agile teams can deliver new features quicker and more effectively. What this pattern has done more than anything to date is spark organizational transformations, setting the foundation for future application development. In practice, however, there are a number of considerations to make that go beyond simply “build, ship, and run,” which changes ho...
Jun. 30, 2016 10:00 AM EDT Reads: 1,200
Gartner is now treating algorithms like they are some kind of innovative addition to the modern digital discussion. Presumably the brilliant minds there have some novel insight into algorithms and, yes, the Algorithm Economy that CIOs should sit up and take notice of. Not only are algorithms nothing new, but much of what Gartner is saying about them is obvious. The bigger picture here is that software continues to improve, and enterprises are becoming increasingly software-driven, in part bec...
Jun. 17, 2016 04:07 PM EDT Reads: 869
The Internet of Things is clearly many things: data collection and analytics, wearables, Smart Grids and Smart Cities, the Industrial Internet, and more. Cool platforms like Arduino, Raspberry Pi, Intel's Galileo and Edison, and a diverse world of sensors are making the IoT a great toy box for developers in all these areas. In this Power Panel at @ThingsExpo, moderated by Conference Chair Roger Strukhoff, panelists discussed what things are the most important, which will have the most profound...
Jun. 12, 2016 09:00 PM EDT Reads: 5,292
The Internet of Things (IoT) is growing rapidly by extending current technologies, products and networks. By 2020, Cisco estimates there will be 50 billion connected devices. Gartner has forecast revenues of over $300 billion, just to IoT suppliers. Now is the time to figure out how you’ll make money – not just create innovative products. With hundreds of new products and companies jumping into the IoT fray every month, there’s no shortage of innovation. Despite this, McKinsey/VisionMobile data...
Jun. 12, 2016 02:45 AM EDT Reads: 3,832
NHK, Japan Broadcasting, will feature the upcoming @ThingsExpo Silicon Valley in a special 'Internet of Things' and smart technology documentary that will be filmed on the expo floor between November 3 to 5, 2015, in Santa Clara. NHK is the sole public TV network in Japan equivalent to the BBC in the UK and the largest in Asia with many award-winning science and technology programs. Japanese TV is producing a documentary about IoT and Smart technology and will be covering @ThingsExpo Silicon Val...
Jun. 8, 2016 10:30 PM EDT Reads: 4,728
SYS-CON Events announced today that Men & Mice, the leading global provider of DNS, DHCP and IP address management overlay solutions, will exhibit at SYS-CON's 18th International Cloud Expo®, which will take place on June 7-9, 2016, at the Javits Center in New York City, NY. The Men & Mice Suite overlay solution is already known for its powerful application in heterogeneous operating environments, enabling enterprises to scale without fuss. Building on a solid range of diverse platform support,...
Jun. 8, 2016 06:45 PM EDT Reads: 4,223
Internet of @ThingsExpo, taking place June 7-9, 2016 at Javits Center, New York City and Nov 1-3, 2016, at the Santa Clara Convention Center in Santa Clara, CA, is co-located with the 18th International @CloudExpo and will feature technical sessions from a rock star conference faculty and the leading industry players in the world and ThingsExpo New York Call for Papers is now open.
Jun. 8, 2016 03:45 PM EDT Reads: 3,373
SYS-CON Events announced today that Catchpoint Systems, Inc., a provider of innovative web and infrastructure monitoring solutions, has been named “Silver Sponsor” of SYS-CON's DevOps Summit at 18th Cloud Expo New York, which will take place June 7-9, 2016, at the Javits Center in New York City, NY. Catchpoint is a leading Digital Performance Analytics company that provides unparalleled insight into customer-critical services to help consistently deliver an amazing customer experience. Designed...
Jun. 8, 2016 03:00 PM EDT Reads: 3,344
@DevOpsSummit taking place June 7-9, 2016 at Javits Center, New York City, and Nov 1-3, 2016, at the Santa Clara Convention Center in Santa Clara, CA, is co-located with the 18th International @CloudExpo and will feature technical sessions from a rock star conference faculty and the leading industry players in the world.
Jun. 8, 2016 01:00 PM EDT Reads: 4,535
Cloud Expo, Inc. has announced today that Andi Mann returns to 'DevOps at Cloud Expo 2016' as Conference Chair The @DevOpsSummit at Cloud Expo will take place on June 7-9, 2016, at the Javits Center in New York City, New York. "DevOps is set to be one of the most profound disruptions to hit IT in decades," said Andi Mann. "It is a natural extension of cloud computing, and I have seen both firsthand and in independent research the fantastic results DevOps delivers. So I am excited to help the g...
Jun. 8, 2016 11:00 AM EDT Reads: 3,794
Korean Broadcasting System (KBS) will feature the upcoming 18th Cloud Expo | @ThingsExpo in a New York news documentary about the "New IT for the Future." The documentary will cover how big companies are transmitting or adopting the new IT for the future and will be filmed on the expo floor between June 7-June 9, 2016, at the Javits Center in New York City, New York. KBS has long been a leader in the development of the broadcasting culture of Korea. As the key public service broadcaster of Korea...
Jun. 8, 2016 10:00 AM EDT Reads: 2,688
SYS-CON Events announced today that Addteq will exhibit at SYS-CON's @DevOpsSummit at Cloud Expo New York, which will take place on June 7-9, 2016, at the Javits Center in New York City, NY. Addteq is one of the top 10 Platinum Atlassian Experts who specialize in DevOps, custom and continuous integration, automation, plugin development, and consulting for midsize and global firms. Addteq firmly believes that automation is essential for successful software releases. Addteq centers its products a...
Jun. 8, 2016 09:45 AM EDT Reads: 2,644
In the rush to compete in the digital age, a successful digital transformation is essential, but many organizations are setting themselves up for failure. There’s a common misconception that the process is just about technology, but it’s not. It’s about your business. It shouldn’t be treated as an isolated IT project; it should be driven by business needs with the committed involvement of a range of stakeholders.
Jun. 8, 2016 02:15 AM EDT Reads: 3,732
SYS-CON Events announced today that FalconStor Software® Inc., a 15-year innovator of software-defined storage solutions, will exhibit at SYS-CON's 18th International Cloud Expo®, which will take place on June 7-9, 2016, at the Javits Center in New York City, NY. FalconStor Software®, Inc. (NASDAQ: FALC) is a leading software-defined storage company offering a converged, hardware-agnostic, software-defined storage and data services platform. Its flagship solution FreeStor®, utilizes a horizonta...
Jun. 7, 2016 07:00 PM EDT Reads: 4,341
With major technology companies and startups seriously embracing IoT strategies, now is the perfect time to attend @ThingsExpo 2016 in New York and Silicon Valley. Learn what is going on, contribute to the discussions, and ensure that your enterprise is as "IoT-Ready" as it can be! Internet of @ThingsExpo, taking place Nov 3-5, 2015, at the Santa Clara Convention Center in Santa Clara, CA, is co-located with 17th Cloud Expo and will feature technical sessions from a rock star conference faculty ...
Jun. 7, 2016 04:30 PM EDT Reads: 6,056
SYS-CON Events announced today that Column Technologies will exhibit at SYS-CON's @DevOpsSummit at Cloud Expo, which will take place on June 7-9, 2016, at the Javits Center in New York City, NY. Established in 1998, Column Technologies is a global technology solutions provider with over 400 employees, headquartered in the United States with offices in Canada, India, and the United Kingdom. Column Technologies provides “Best of Breed” technology solutions that automate the key DevOps principal...
Jun. 7, 2016 04:15 PM EDT Reads: 3,454
SYS-CON Events announced today that SoftLayer, an IBM Company, has been named “Gold Sponsor” of SYS-CON's 18th Cloud Expo, which will take place on June 7-9, 2016, at the Javits Center in New York, New York. SoftLayer, an IBM Company, provides cloud infrastructure as a service from a growing number of data centers and network points of presence around the world. SoftLayer’s customers range from Web startups to global enterprises.
Jun. 7, 2016 01:00 PM EDT Reads: 2,880