🧼 Spec-Driven API Modernization 🌐

╔═══════════════════════════════════════════════════════════════╗
║                                                               ║
║    █████╗ ██████╗ ██╗    ███╗   ███╗ ██████╗ ██████╗        ║
║   ██╔══██╗██╔══██╗██║    ████╗ ████║██╔═══██╗██╔══██╗       ║
║   ███████║██████╔╝██║    ██╔████╔██║██║   ██║██║  ██║       ║
║   ██╔══██║██╔═══╝ ██║    ██║╚██╔╝██║██║   ██║██║  ██║       ║
║   ██║  ██║██║     ██║    ██║ ╚═╝ ██║╚██████╔╝██████╔╝       ║
║   ╚═╝  ╚═╝╚═╝     ╚═╝    ╚═╝     ╚═╝ ╚═════╝ ╚═════╝        ║
║                                                               ║
║              ◇ SOAP TO REST EVOLUTION ◇                      ║
║                                                               ║
║         ▓▓▓ SPECIFICATION-DRIVEN APIS ▓▓▓                    ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

🌟 MISSION BRIEFING

Welcome to Spec-Driven API Modernization — where we transform messy SOAP + undocumented REST into beautiful, spec-first APIs! 🧼✨

⚡ POWER-UP UNLOCKED: Spec-Driven Development
🎯 DIFFICULTY: Intermediate (P2)
🛠️ TECH STACK: OpenAPI • REST • SOAP
⏱️ ESTIMATED RUNTIME: 4-6 hours

---

🕹️ THE EVOLUTION

┌─────────────────────────────┐
│  🏛️ LEGACY CHAOS             │
│                             │
│  CargoLink Express          │
│  • WCF SOAP services        │
│  • Undocumented REST        │
│  • Inconsistent models      │
│  • No versioning            │
└──────────┬──────────────────┘
           │
           ▼
   ┌───────────────────┐
   │ SOAP DECODED 🧼   │
   │ WSDL → OpenAPI    │
   │ Contracts extracted│
   └──────┬────────────┘
           │
           ▼
   ┌───────────────────┐
   │ REST ACTIVATED 🌐 │
   │ Endpoints analyzed │
   │ Implicit contracts │
   └──────┬────────────┘
           │
           ▼
   ┌─────────────────────┐
   │ OPENAPI GENERATED 📜│
   │ Unified spec        │
   │ Inconsistencies fixed│
   └──────┬──────────────┘
           │
           ▼
   ┌──────────────────────┐
   │ API MODERNIZED ✨     │
   │ ASP.NET Core 9       │
   │ Spec-first           │
   │ Azure API Management │
   │ SOAP compatibility   │
   └──────────────────────┘

---

🎨 THE BATTLEFIELD

🏛️ LEGACY SYSTEM: CargoLink Express

A shipping logistics platform with dual personalities:

╔════════════════════════════════════════════╗
║  🧼 SOAP SERVICES (Enterprise clients)    ║
║     • WCF .NET Framework 4.6.2           ║
║     • XML request/response               ║
║     • WSDL contracts                     ║
║     • WS-Security auth                   ║
║                                          ║
║  🌐 REST ENDPOINTS (Mobile apps)         ║
║     • ASP.NET Web API 1.x                ║
║     • JSON request/response              ║
║     • NO documentation!                  ║
║     • Custom header API keys             ║
╚════════════════════════════════════════════╝

      ⚠️ SAME DATA, DIFFERENT MODELS ⚠️

💣 API INCONSISTENCIES:

SOAP: ShipmentRequest.DeliveryAddress
REST: ShipmentDto.delivery_address

SOAP: <Status>InTransit</Status>
REST: { "status": "IN_TRANSIT" }

SOAP: SOAP Faults
REST: { "error": "whatever" }

❌ No versioning
❌ Different auth mechanisms
❌ Duplicated business logic
❌ Tribal knowledge required

---

🎯 TARGET ARCHITECTURE

Unified, Spec-First API:

┌───────────────────────────────────────────────┐
│     📜 OPENAPI 3.1 SPEC (Source of Truth)    │
│                                               │
│  ✅ Unified models                            │
│  ✅ Consistent errors                         │
│  ✅ Standardized naming                       │
│  ✅ Version management                        │
└──────────────┬────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────┐
│         🌐 AZURE API MANAGEMENT              │
│                                              │
│  ┌──────────────┐      ┌─────────────────┐  │
│  │ SOAP Endpoint│──┐   │ REST Endpoint   │  │
│  │(compatibility)│  │   │(native)         │  │
│  └──────────────┘  │   └─────────────────┘  │
│         │          │            │            │
│         └──────────┴────────────┘            │
│                    │                         │
│              ┌─────▼──────┐                  │
│              │SOAP-to-REST│                  │
│              │Translation │                  │
│              └─────┬──────┘                  │
└────────────────────┼─────────────────────────┘
                     │
                     ▼
        ┌────────────────────────┐
        │ ASP.NET Core 9 API     │
        │                        │
        │ Built from OpenAPI Spec│
        │ OAuth2/OIDC (Entra ID) │
        └────────────────────────┘

---

🚀 QUEST OBJECTIVES

✅ Extract SOAP contracts from WSDL files
✅ Analyze undocumented REST endpoints
✅ Generate unified OpenAPI 3.1 specification
✅ Resolve SOAP ↔ REST inconsistencies
✅ Implement spec-first ASP.NET Core 9 API
✅ Configure Azure APIM with SOAP translation
✅ Validate backward compatibility

---

💎 POWER-UPS YOU'LL UNLOCK

╔════════════════════════════════════════════╗
║  🧼 WSDL PARSING     │ SOAP → OpenAPI     ║
║  🌐 REST ANALYSIS    │ Implicit contracts ║
║  📜 SPEC UNIFICATION │ Merged OpenAPI     ║
║  🔧 CODE GENERATION  │ From spec to code  ║
║  🔄 SOAP TRANSLATION │ Backward compat    ║
║  🔐 UNIFIED AUTH     │ OAuth2/OIDC        ║
╚════════════════════════════════════════════╝

---

📦 BRANCH STRUCTURE

Branch	Description	Status
main	📖 Complete lab documentation	✅
legacy	🏛️ Mixed SOAP/REST system	🔴
solution	✨ Unified OpenAPI-first API	🟢
step-1-wsdl-analysis	🧼 SOAP contract extraction	🔷
step-2-rest-analysis	🌐 REST contract extraction	🔷
step-3-unified-spec	📜 OpenAPI 3.1 generated	🔷
step-4-implementation	🔨 ASP.NET Core API built	🔷
step-5-apim-setup	☁️ Azure APIM configured	🟢

---

🎮 START GAME

Prerequisites (Check Your Inventory)

• ✅ C# and ASP.NET experience
• ✅ SOAP and REST concepts
• ✅ OpenAPI/Swagger knowledge
• ✅ Azure subscription (for API Management)

Quick Start

# 1. Clone the repo
git clone <repo-url>
cd appmodlab-spec-driven-api-modernization

# 2. Checkout legacy branch
git checkout legacy

# 3. Run SOAP services
cd CargoLink.SoapServices
dotnet run

# 4. Run REST API
cd ../CargoLink.RestApi
dotnet run

# 5. Test both APIs (Postman collection included)

---

🌈 THE MODERNIZATION JOURNEY

🧼 STEP 1: SOAP DECODED

SOAP DECODED 🧼
├── ShipmentService.wsdl parsed
├── TrackingService.wsdl parsed
├── RateService.wsdl parsed
├── Data types extracted
└── Operations mapped

🌐 STEP 2: REST ACTIVATED

REST ACTIVATED 🌐
├── ShipmentController analyzed
├── TrackingController analyzed
├── QuoteController analyzed
├── Implicit contracts documented
└── Inconsistencies identified

📜 STEP 3: OPENAPI GENERATED

OPENAPI GENERATED 📜
├── Models unified (SOAP + REST)
├── Naming standardized
├── Error responses consistent
├── Authentication unified (OAuth2)
└── OpenAPI 3.1 spec complete

🔨 STEP 4: API IMPLEMENTED

API MODERNIZED 🔨
├── ASP.NET Core 9 project created
├── NSwag code generation from spec
├── Business logic implemented
├── OAuth2/OIDC configured
└── All endpoints functional

☁️ STEP 5: APIM CONFIGURED

APIM SETUP ☁️
├── Azure API Management deployed
├── Import OpenAPI spec
├── SOAP-to-REST translation policy
├── Rate limiting configured
└── Developer portal published

---

🎬 FINAL BOSS: End-to-End Flow

Test the complete modernization:

1. 🧼 Legacy SOAP client calls SOAP endpoint
2. 🔄 Azure APIM translates to REST
3. 🌐 New ASP.NET Core API processes request
4. 📦 Response flows back via APIM
5. ✅ SOAP client receives SOAP response
6. 🎉 Backward compatibility achieved!

Meanwhile:

7. 📱 Mobile app calls REST endpoint directly
8. 🌐 Same ASP.NET Core API processes
9. 📡 Clean JSON response
10. 🎉 Modern client happy!

---

🏆 ACHIEVEMENT UNLOCKED

Complete this lab to earn:

🏆 SOAP WHISPERER — WSDL to OpenAPI conversion
🌐 REST REVEALER — Documented undocumented APIs
📜 SPEC UNIFIER — Merged SOAP + REST to OpenAPI
🔄 TRANSLATION MASTER — SOAP-to-REST backward compat

---

🎪 THE TECH STACK

╔════════════════════════════════════════════╗
║ LEGACY SOAP │ WCF .NET Framework 4.6.2   ║
║ LEGACY REST │ ASP.NET Web API 1.x        ║
║ MODERN API  │ ASP.NET Core 9             ║
║ SPEC        │ OpenAPI 3.1                ║
║ GATEWAY     │ Azure API Management       ║
║ AUTH        │ OAuth2/OIDC (Entra ID)     ║
║ CODEGEN     │ NSwag / AutoRest           ║
║ DATABASE    │ SQL Server / Azure SQL     ║
╚════════════════════════════════════════════╝

---

🎯 KEY OPERATIONS

The API Evolution

BEFORE:
┌────────┐     ┌────────┐
│ SOAP   │     │ REST   │
│Service │     │Service │
└───┬────┘     └───┬────┘
    │              │
    ├─ Different models
    ├─ Different auth
    ├─ Different errors
    └─ Duplicated logic

AFTER:
┌─────────────────┐
│  OpenAPI Spec   │
└────────┬────────┘
         │
    ┌────▼─────┐
    │ Unified  │
    │   API    │
    └────┬─────┘
         │
    ┌────┴─────┐
    │   APIM   │
    ├──────────┤
    │ SOAP In  │→│
    │ REST In  │→├─→ REST Out
    └──────────┘

One API, Multiple Clients, All Happy! 🎉

---

🌟 CREDITS

Organization: EmeaAppGbb
Category: Spec-Driven Development
Priority: P2
Estimated Time: 4-6 hours

---

╔═══════════════════════════════════════════════╗
║                                               ║
║   READY TO MODERNIZE YOUR APIS? 🧼🌐          ║
║                                               ║
║          Press START to begin...              ║
║                                               ║
║      [ Check APPMODLAB.md for details ]       ║
║                                               ║
╚═══════════════════════════════════════════════╝

🎮 INSERT COIN TO CONTINUE 🎮

---

Made with 💜 by the AppMod Labs Squad