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 experi

Answer 1

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.

Answer 2

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.

Answer 3

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.