Which is the better approach to web services - contract first or contract last?

Question

Which is the better approach to developing web services; contract first or contract last?
What are the advantages and disadvantages of each?

Which do you have experience with?

EDIT This question is about the implementation of a web service (read: SOAP) The question is whether the implementation classes should be coded first and the WSDL and XSD schema generated from that (contract last) or the WSDL and XSD schema written first and the implementation classes generated (contract first)

Guyton

Since the question asks about the advantages and disadvantaages of each side, I don't see that it's subjective. – Suppliant

Answer 1

Contract-first is the generally accepted 'best practice.'

It makes you be very clear with both the producer and consumer of the service exactly what is needed and what is expected. This becomes especially important when you start trying to convert java types -> xml types. You're also able to reuse schemas across different web service.

Uneven

How do you define something like a stream in your contract for something like large file uploads? – Vories

@Vories No need to define that in the contract -- that is already a standard. One can use MIME (old style) or MTOM (most often used now). – Elbert

Answer 2

I've used both approaches. My suggestion is to use contract first schema, but code first WSDL.

Writing a WSDL file has a lot of weird nuances like bindings, ports and such. I'd rather have this done by tools rather than by hand. There are tools to help do this, but none of them are simpler than

@WebService
public ...

At the very least you can verify your deployment.

For the schema, I suggested contract first because the XML Schema language is far richer than what you can describe in Java. An example I usually give is showing that XML Schema can restrict the size of a string and apply a regular expression pattern. Doing that in Java and annotations looks a bit messier.

Another advantage of doing the schema as contract first is the presence of tools to convert your schema file into HTML documentation.

The XJC tool can generate the requisite class files. However, I would only recommend doing that at start.

In the end you should take the generated WSDL file and work with that instead. That way you can use wsimport and verify that the whole thing from WSDL to Schema is valid.

You can deploy with the WSDL file by using the wsdlLocation attribute in your @WebService implementation and the application server will fix the binding data for you when users request the WSDL from the server, but you still retain your annotations. Otherwise your annotations will not appear on the requested WSDL files.

Coeternity

Your hybrid approach is interesting, but it's not clear to me how you put it in practice. You first create a schema describing the bean classes used by the WS, then you create the classes with XJC, but how do you use this schema in a generated WSDL? – Armstead

Agreed, this is very useful. Spring-WS does this, but takes it one step further, by doing contract-first based on the schema, and generating the WSDL at runtime when the WSDL is requested. That way, one never has to mess with the WSDL at all. – Elbert

@Armstead just use the classes on the method of the service. github.com/trajano/app/tree/master/app-web has an example of this. – Coeternity

Answer 3

I suspect the answer is a definite "it depends."

The issue is that if you build and publish your contract, you're bound by it. This makes change harder. not impossible, but harder.

On the other hand, it's quicker to mess with the contract than with code, if you're comfortable with schemata etc. So you can do some incremental change in the contract.

Aren't there also tools that will generate a code skeleton from the WSDL? I'm almost positive there are. If so, you might do well to make the schemata the "code" item, and generate code from it.

Mansized

There are such tools. In the Java space the Apache Software Foundation and others provide a number of tools which can accomplish generation of code. eg XMLBeans. Also a number of APIs can do it. The JAXB API is all about binding xml to Java objects, and the JAX-WS API includes a tool wsimport, which parses a WSDL and generates Java classes. – Guyton