Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 36 ยท WSDL and Contracts

Contract-First vs Code-First Design

Compare designing SOAP services from the WSDL (contract-first) with generating the WSDL from code (code-first), learn versioning rules and detect breaking changes between contract versions.

Every SOAP service has two artifacts that must agree: the code that runs, and the contract (WSDL and schemas) that clients read. One of them is written by hand; the other is produced from it. Which one you write by hand is the most important design decision of a SOAP project, and it has a name: code-first or contract-first.

Code-first

You write the implementation (a Java class with @WebService, a C# class with [ServiceContract]) and the framework generates the WSDL when the service starts.

flowchart LR
    A["Write the code<br/>(annotated classes)"] --> B["Framework generates<br/>WSDL + XSD"]
    B --> C["Clients download ?wsdl<br/>and generate stubs"]

The contract follows the code.

Advantages: quick to start, one source of truth for developers, no XML Schema skills needed. Disadvantages: the generated schema reflects your internal class names and quirks; a harmless refactor (renaming a field, switching a collection type) silently changes the contract; platform-specific types (DataSet, HashMap, Java Date) leak into the contract and break other platforms; and you often cannot control namespaces, element order or optionality precisely.

Contract-first

You write the XSD and WSDL first, agree on them with the consumers, and generate server skeletons and client stubs from them (wsimport, svcutil, xsd.exe, Apache CXF wsdl2java, Zeep).

flowchart LR
    A["Design the contract<br/>(XSD + WSDL)"] --> B["Generate server<br/>skeleton"]
    A --> C["Generate client<br/>stubs"]
    B --> D["Implement the<br/>business logic"]

The code follows the contract.

Advantages: the contract is stable and reviewed; types are chosen for interoperability; several teams can start in parallel; changes are deliberate. Disadvantages: needs schema skills, more upfront work, and generated code must be kept in sync.

Question Code-first Contract-first
Fast prototype? yes slower
Many external consumers? risky recommended
Strict regulations / partner-mandated WSDL? not possible the only way
Refactoring safety low high
Cross-platform data types easy to get wrong designed in

Rule of thumb: internal, short-lived service, one consumer can be code-first; public or partner-facing, long-lived service should be contract-first. Many teams do a hybrid: they write the XSD by hand (the data contract) and let the framework generate the WSDL around it.

Inferring a schema from code

To feel what code-first generators do, and where they go wrong, here is a mini generator. It looks at a sample object and writes an XSD complex type. Notice what it cannot know: whether note is optional, what the legal range of quantity is, or whether price is a decimal. A person has to say those things, which is exactly why handwritten contracts are better.

Node.js A tiny code-first schema generator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Detecting breaking changes

Whichever approach you use, the contract is a promise. Changing it can break clients you have never met. This second program compares two versions of a contract (reduced to operations and fields) and classifies each difference as breaking or compatible. Wiring a check like this into your build is one of the best investments a SOAP team can make.

Node.js Breaking or compatible?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Versioning strategies

Once a contract is public you will have to change it. Options, from gentlest to roughest:

  1. Compatible evolution. Add optional elements and new operations. Do not rename, remove or retype. Clients written for the old version keep working (they must ignore unknown elements; set the receiving side to be lenient).
  2. New operation. Keep PlaceOrder, add PlaceOrderV2. Simple, a little ugly.
  3. New namespace and endpoint. urn:orders:v2 at /ws/v2/orders. Both versions run side by side; clients migrate on their own schedule. The usual choice for breaking changes.
  4. Version in a header. Possible but harder for tools; rarely chosen.

Retire old versions on a published schedule and monitor which clients still call them.

Always keep the contract under version control next to the code, and run a breaking-change check in the build. Many teams also publish a sample request and response for every operation inside the WSDL documentation element.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which approach fits a long-lived service with many external partners best?

    A designed, reviewed, stable contract protects many consumers from accidental changes.
  2. 2. Which change to a published schema is BREAKING for existing clients?

    Old clients do not send the new required element, so their requests become invalid.
  3. 3. Why can a code-first refactor be dangerous?

    The contract is generated from code, so renaming a field or changing a type changes what clients see.
  4. 4. What is the safest way to introduce a breaking change?

    Running versions side by side lets clients migrate on their own schedule.

Summary

  • Code-first generates the contract from code; contract-first generates code from the contract.
  • Prefer contract-first for external, long-lived or regulated services; code-first is fine for quick internal ones.
  • Generators cannot know optionality, ranges or business types, so hand-designed schemas are more precise.
  • Evolve contracts compatibly: add optional things, never rename or remove.
  • Use a new namespace and endpoint for breaking changes, and automate a breaking-change check.

Next: WS-Security: Authentication and Tokens