API Contract Diff Tool

A Java command-line tool for comparing API responses across versions and identifying contract-breaking changes before integration.

---

What is API Contract Diff Tool?

API Contract Diff Tool is a Java-based command-line utility that compares two versions of an API's JSON response and identifies changes that may affect compatibility.

It recursively traverses nested JSON objects and arrays to detect added, removed, and modified fields, then produces a structured field-level diff and a simple risk assessment.

The goal is to make API changes visible before they reach integration, helping developers quickly understand what changed and evaluate potential compatibility risks.

---

How It Works

The tool accepts two JSON files:

old.json
new.json

Both responses are parsed using Gson and passed through a recursive comparison engine.

Old JSON ──────┐
               │
               ▼
          Parse with Gson
               │
               ▼
       Recursive Comparison
               │
      ┌────────┼────────┐
      ▼        ▼        ▼
   Objects   Arrays   Primitives
      │        │        │
      ▼        ▼        ▼
   Compare  Compare  Compare
    Keys    Indexes   Values
      │        │        │
      └────────┼────────┘
               ▼
       Collect Differences
               │
       ┌───────┼────────┐
       ▼       ▼        ▼
     Added   Removed  Changed
               │
               ▼
        Risk Assessment
               │
               ▼
          CLI Output

Nested objects are compared recursively, while arrays are traversed element by element.

Each detected change is recorded using its exact JSON path, allowing developers to identify where a difference occurred.

---

CLI Output

---

Risk Assessment

The tool classifies changes into four simple risk levels:

• HIGH — Fields were removed
• MEDIUM — Existing values were modified
• LOW — Only new fields were added
• SAFE — No changes were detected

This provides developers with a quick signal when reviewing API changes before integration.

---

Project Structure

API-Contract-Diff-Tool/
│
├── assets/
│   └── APIDiffTool.png
│
├── lib/
│   └── gson-2.10.1.jar
│
├── src/
│   └── CompareAPI.java
│
├── old.json
├── new.json
├── README.md
├── Dockerfile
└── .gitignore

---

Running the Tool

Compile:

javac -cp "lib/gson-2.10.1.jar" -d out src/CompareAPI.java

Run:

java -cp "out;lib/gson-2.10.1.jar" CompareAPI old.json new.json

Or provide your own JSON files:

java -cp "out;lib/gson-2.10.1.jar" CompareAPI <old-json> <new-json>

---

Running with Docker

Build the image:

docker build -t api-contract-diff-tool .

Run the tool:

docker run --rm api-contract-diff-tool

---

Tech Stack

• Java 21
• Gson
• CLI
• Docker

---

Key Concepts

• Recursive JSON comparison
• JSON object and array traversal
• Field-level change detection
• Added, removed, and modified fields
• JSON type change detection
• Command-line tool development