API Architecture¶

XConnect API - Complete Technical Architecture Documentation

Overview¶

XConnect is WithinEarth's core API platform that provides unified access to 56+ hotel suppliers. This document covers the complete A-Z architecture including structure, dependencies, failover mechanisms, high availability, and operational details.

API Infrastructure Summary¶

Component	Count	Details
API Servers	7	Windows Server + .NET 9
Application Pools	301	43 pools × 7 servers
Load Balancers	2	HAProxy Aloha HA pair
Supplier Proxies	7	Outbound supplier calls
SQL Databases	16+	Primary + replicas + logs
MongoDB Servers	8	Cache + logs + mappings
Redis Nodes	3	Cluster (202, 203, 204)
Daily API Calls	~7.3M	Search requests
Daily Bookings	~2,746	Confirmed reservations

Complete Architecture Diagram¶

graph LR
    subgraph CLIENTS["B2B Clients"]
        C["627+ Agents<br/>OTAs, Agencies<br/>Corporate"]
    end

    subgraph ENTRY["Entry Point"]
        VIP["VIP: 89.149.192.33"]
        HAP["HAProxy HA<br/>36 / 38"]
    end

    subgraph API_LAYER["API Servers (7)"]
        API1["API-1: .134"]
        API2["API-2: .135"]
        API3["API-3: .139"]
        API4["API-4: .137"]
        API5["API-5: .35"]
        API6["API-6: .166"]
        API7["API-7: .167"]
    end

    subgraph PROXY["Supplier Proxies (7)"]
        SP["Proxy 41-47"]
    end

    subgraph DATA["Data Layer"]
        MAIN["MainDB .130:1988<br/>CRITICAL - SPOF"]
        REP["Replicas (6)<br/>VIP .5"]
        MONGO["MongoDB (8)"]
        REDIS["Redis Cluster<br/>202, 203, 204"]
    end

    subgraph SUP["56+ Suppliers"]
        S1["Agoda, Expedia"]
        S2["Booking, HotelBeds"]
        S3["+ 52 more"]
    end

    C --> VIP
    VIP --> HAP
    HAP --> API1 & API2 & API3 & API4 & API5 & API6 & API7
    API1 & API2 & API3 & API4 & API5 & API6 & API7 --> SP
    API1 & API2 & API3 & API4 & API5 & API6 & API7 --> MAIN
    API1 & API2 & API3 & API4 & API5 & API6 & API7 --> REP
    API1 & API2 & API3 & API4 & API5 & API6 & API7 --> MONGO
    API1 & API2 & API3 & API4 & API5 & API6 & API7 --> REDIS
    SP --> S1 & S2 & S3

    style VIP fill:#4CAF50
    style HAP fill:#2196F3
    style MAIN fill:#FF0000,color:#fff
    style REDIS fill:#E91E63

API Endpoints (Complete Reference)¶

Core Booking Flow¶

#	Endpoint	Method	Description	Avg Response
1	`/api/xconnect/availability`	POST	Search hotel availability	2-5 sec
2	`/api/xconnect/ReCheck`	POST	Verify price before booking	1-3 sec
3	`/api/xconnect/CancellationPolicy`	POST	Get cancellation terms	0.5-1 sec
4	`/api/xconnect/PreBook`	POST	Reserve room (hold)	2-5 sec
5	`/api/xconnect/Book`	POST	Confirm booking	3-8 sec
6	`/api/xconnect/BookingDetail`	POST	Get booking info	0.5-1 sec
7	`/api/xconnect/CancelBooking`	POST	Cancel reservation	2-5 sec

Extended Endpoints¶

Endpoint	Method	Description
`/api/xconnect/availabilitywithCancellation`	POST	Search with cancellation terms
`/api/xconnect/availabilitywithCancellationv2`	POST	V2 with enhanced cancellation
`/api/xconnect/CancellationPolicyMulti`	POST	Batch cancellation policies
`/api/xconnect/BookingDetailV2`	POST	Enhanced booking details
`/api/xconnect/BookingDetail_Full`	POST	Complete booking data
`/api/xconnect/CheckHotelCancellationCharges`	POST	Calculate cancellation fees

Static Data Endpoints¶

Endpoint	Method	Description
`/api/xconnect/Countries`	POST	List all countries
`/api/xconnect/Cities`	POST	List cities by country
`/api/xconnect/GetStaticDataByCity`	POST	Hotel static data for a city
`/api/xconnect/allcitieswithcountry`	POST	All cities with country mapping

Health & Monitoring¶

Endpoint	Method	Description
`/api/xconnect/healthcheck`	GET	API health status
`/api/xconnect/GetThreadInfo`	GET	Thread pool information

API Request Flow¶

Search Flow (availability endpoint)¶

sequenceDiagram
    participant Client
    participant HAProxy
    participant API as API Server
    participant Cache as Redis/MongoDB
    participant Proxy as Supplier Proxy
    participant DB as SQL Server
    participant Supplier

    Client->>HAProxy: POST /availability
    HAProxy->>API: Route to backend pool

    API->>DB: Get agent config
    API->>Cache: Check cached results

    alt Cache Hit
        Cache-->>API: Return cached data
        API-->>Client: Response (fast)
    else Cache Miss
        API->>Proxy: Parallel supplier calls

        par Supplier Calls
            Proxy->>Supplier: Agoda search
            Proxy->>Supplier: Expedia search
            Proxy->>Supplier: Booking.com search
            Proxy->>Supplier: Other suppliers...
        end

        Supplier-->>Proxy: Responses
        Proxy-->>API: Aggregated results

        API->>Cache: Store results (35 min TTL)
        API->>DB: Log search (async)
        API-->>Client: Response
    end

Booking Flow¶

sequenceDiagram
    participant Client
    participant API as API Server
    participant DB as SQL Primary
    participant Proxy as Supplier Proxy
    participant Supplier
    participant Queue as RabbitMQ

    Client->>API: POST /ReCheck
    API->>Proxy: Verify availability
    Proxy->>Supplier: Check price
    Supplier-->>API: Confirmed price
    API-->>Client: ReCheck response

    Client->>API: POST /PreBook
    API->>Proxy: Reserve room
    Proxy->>Supplier: Hold booking
    Supplier-->>API: PreBook confirmation
    API->>DB: Save PreBook record
    API-->>Client: PreBook response

    Client->>API: POST /Book
    API->>Proxy: Confirm booking
    Proxy->>Supplier: Complete booking
    Supplier-->>API: Booking confirmation
    API->>DB: Save booking record
    API->>Queue: Queue notifications
    API-->>Client: Booking response

API Types & Categories¶

By Function¶

Type	Endpoints	Purpose
Search	availability, availabilitywithCancellation	Find hotels
Verification	ReCheck, CancellationPolicy	Validate before booking
Transaction	PreBook, Book, CancelBooking	Execute bookings
Query	BookingDetail, BookingDetailV2	Retrieve data
Static	Countries, Cities, GetStaticDataByCity	Reference data
Admin	healthcheck, GetThreadInfo	Monitoring

By Response Time¶

Category	SLA	Endpoints
Fast (<1s)	99.9%	healthcheck, Countries, Cities
Medium (1-3s)	99.5%	ReCheck, CancellationPolicy, BookingDetail
Slow (3-10s)	99%	availability, PreBook, Book

By Load¶

Category	Requests/Day	Endpoints
High	7M+	availability (main search)
Medium	100K-500K	ReCheck, CancellationPolicy
Low	<100K	Book, CancelBooking, static data

API Dependencies¶

Internal Dependencies¶

graph LR
    subgraph API["XConnect API"]
        CTRL["Controller Layer"]
        BAL["Business Access Layer"]
        DAL["Data Access Layer"]
        SUP["Supplier Module"]
    end

    subgraph EXTERNAL["External Services"]
        SQL["SQL Server"]
        MONGO["MongoDB"]
        REDIS["Redis"]
        RABBIT["RabbitMQ"]
        PROXY["Supplier Proxy"]
    end

    CTRL --> BAL
    BAL --> DAL
    BAL --> SUP
    DAL --> SQL
    DAL --> MONGO
    BAL --> REDIS
    BAL --> RABBIT
    SUP --> PROXY

    style CTRL fill:#4CAF50
    style BAL fill:#2196F3
    style DAL fill:#FF9800
    style SUP fill:#9C27B0

Dependency Matrix¶

API Endpoint	SQL	MongoDB	Redis	RabbitMQ	Suppliers
availability	READ	READ/WRITE	READ/WRITE	-	YES
ReCheck	READ	READ	READ	-	YES
CancellationPolicy	READ	READ	READ	-	YES
PreBook	READ/WRITE	READ	READ	-	YES
Book	READ/WRITE	WRITE	WRITE	WRITE	YES
BookingDetail	READ	READ	READ	-	-
CancelBooking	READ/WRITE	WRITE	WRITE	WRITE	YES
Static Data	READ	-	READ	-	-

External Dependencies (Suppliers)¶

Supplier	Protocol	Auth	Timeout
Agoda	REST/JSON	API Key	40s
Expedia	REST/JSON	OAuth	40s
Booking.com	REST/JSON	API Key	40s
HotelBeds	REST/JSON	API Key + Secret	40s
All Others	REST/JSON or SOAP/XML	Various	40s

API Volume & Capacity¶

Current Load (Daily)¶

Metric	Value	Peak
Total Requests	7.3M/day	10M
Searches	7M/day	9M
ReCkhecks	200K/day	400K
Bookings	2,746/day	5,000
Cancellations	500/day	1,000
Static Queries	50K/day	100K

Monthly Volume¶

Month	Searches	Bookings	Revenue
Current	220M	82K	$40M
Average	180M	75K	$35M
Peak	250M	100K	$50M

Requests Per Second (RPS)¶

Time Period	Avg RPS	Peak RPS
All Day Average	2,300	2,800
Business Hours	2,400	2,600
Peak Hours	2,500	3,000
Off Hours	2,200	2,400

High Availability (HA) Architecture¶

Load Balancer HA¶

graph TB
    subgraph CLIENT["Clients"]
        C1["Client Traffic"]
    end

    subgraph VIP["Floating IP"]
        FIP["89.149.192.33<br/>(Active VIP)"]
    end

    subgraph HAPROXY["HAProxy HA Pair"]
        HAP_M["HAProxy Master<br/>10.32.8.36<br/>ACTIVE"]
        HAP_S["HAProxy Standby<br/>10.32.8.38<br/>STANDBY"]
        VRRP["VRRP Heartbeat<br/>(2s interval)"]
    end

    C1 --> FIP
    FIP --> HAP_M
    FIP -.->|Failover| HAP_S
    HAP_M <--> VRRP
    HAP_S <--> VRRP

    style HAP_M fill:#4CAF50
    style HAP_S fill:#FFE4B5
    style FIP fill:#2196F3

HAProxy HA Details:

Setting	Value
Protocol	VRRP (Keepalived)
Detection Time	2 seconds
Failover Time	<1 second
Session Sync	Real-time (Stick tables)
Config Sync	Automatic

API Server HA¶

Aspect	Implementation
Servers	7 Windows API servers
Pools	43 IIS pools per server (301 total)
Distribution	URI-based consistent hashing
Health Checks	Every 30 seconds
Failover	Automatic (unhealthy removed from pool)
Rise/Fall	2 up / 3 down

SQL Replication Database Structure¶

CRITICAL: Single Point of Failure

MainDB (10.32.8.130:1988) is the central database that holds ALL data. Every service relies on MainDB for writes. If MainDB goes down, the entire system goes down. There is currently NO automatic failover for the primary database.

Migration In Progress

We are currently migrating to SQL Server Standard Edition with Always On Availability Groups (AG) to enable automatic failover in case of disaster. This will eliminate the single point of failure.

graph LR
    subgraph MAINDB["MainDB - CENTRAL DATABASE (SPOF)"]
        SQL_P["10.32.8.130:1988<br/>withinearthUpdated<br/>ALL WRITES GO HERE<br/>If down = System down"]
    end

    subgraph SERVICES["All Services Depend on MainDB"]
        API["7 API Servers"]
        OTH["OTH Services"]
        CM["Channel Managers"]
        B2B["B2B Portal"]
    end

    subgraph REPLICAS["Read Replicas (Mapping/Read-Only)"]
        VIP_SQL["HAProxy VIP<br/>10.32.8.5"]
        R1["Replica 1: .143"]
        R2["Replica 2: .149"]
        R3["Replica 3: .9"]
        R4["Replica 4: .85"]
        R5["Replica 5: .37"]
        R6["Replica 6: .39"]
    end

    API --> SQL_P
    OTH --> SQL_P
    CM --> SQL_P
    B2B --> SQL_P

    SQL_P -->|Replication| VIP_SQL
    VIP_SQL --> R1 & R2 & R3 & R4 & R5 & R6

    style SQL_P fill:#FF0000,color:#fff
    style VIP_SQL fill:#4CAF50

MainDB Role:

Aspect	Details
IP Address	10.32.8.130:1988
Database	withinearthUpdated
Role	Primary - All writes
Dependency	ALL services rely on this
Failover	NONE (Single Point of Failure)
Future Plan	SQL Server Standard + AG with auto-failover

Replica Role:

Aspect	Details
Purpose	Read-only queries, mapping data
Load Balancing	HAProxy VIP at 10.32.8.5
Count	6 replicas
Sync	Transaction log replication from MainDB

Redis HA (New 3-Node Cluster)¶

graph TB
    subgraph REDIS["Redis 3-Node Cluster"]
        MASTER["Redis Master<br/>10.32.8.202:6379"]
        REP1["Replica 1<br/>10.32.8.203:6379"]
        REP2["Replica 2<br/>10.32.8.204:6379"]
    end

    MASTER -->|Sync| REP1
    MASTER -->|Sync| REP2

    style MASTER fill:#E91E63
    style REP1 fill:#9C27B0
    style REP2 fill:#9C27B0

Failover Mechanisms¶

1. Load Balancer Failover¶

Normal: Client → VIP (89.149.192.33) → Master (10.32.8.36) → Backend
Failover: Client → VIP (89.149.192.33) → Standby (10.32.8.38) → Backend

Detection: VRRP heartbeat every 2 seconds
Action: VIP automatically moves to standby
Time: <1 second

2. API Server Failover¶

Normal: HAProxy → API-1 (10.32.8.134) → Response
Failover: HAProxy → API-2 (10.32.8.135) → Response

Detection: HTTP health check every 30 seconds
Action: Remove unhealthy server from pool
Recovery: Auto-add when 2 consecutive health checks pass

3. Database Failover¶

Primary Failure:
1. Writes: Queue in RabbitMQ, retry later
2. Reads: Automatically route to replicas via VIP (10.32.8.5)

Replica Failure:
1. HAProxy detects failure (health check)
2. Removes from pool automatically
3. Traffic redistributes to remaining replicas

4. Supplier Failover¶

Supplier Timeout (40s):
1. Mark supplier response as failed
2. Return results from other suppliers
3. Log failure for monitoring
4. Continue serving available inventory

5. MongoDB Failover¶

Search Cache (3 nodes: 51, 52, 53):
1. Try MongoDB-1 (10.32.8.51)
2. If fail → Try MongoDB-2 (10.32.8.52)
3. If fail → Try MongoDB-3 (10.32.8.53)
4. If all fail → Skip cache, call suppliers directly

6. Redis Failover¶

Redis 3-Node Cluster (202, 203, 204):
1. Round-robin load balancing
2. Auto-failover to next node on failure
3. Data replication ensures consistency

API Using Which Services¶

Service Mapping by Endpoint¶

Endpoint	SQL Primary	SQL Replica	MongoDB	Redis	RabbitMQ	Suppliers
availability	Agent config	Hotel data	Cache (51-53)	Session	-	56+
ReCheck	Agent config	Booking verify	Cache read	Session	-	1
PreBook	Write booking	-	Log	Session	-	1
Book	Write booking	-	Log (75)	Session	Notify	1
BookingDetail	-	Read booking	Log read	Cache	-	-
CancelBooking	Write cancel	-	Log (75)	-	Notify	1
Static Data	-	Read static	-	Cache	-	-

MongoDB Service Distribution¶

MongoDB Server	IP	Purpose	Documents
MongoDB-1	10.32.8.51	Search cache	1.6M
MongoDB-2	10.32.8.52	Search cache	800K
MongoDB-3	10.32.8.53	Search cache	3.2M
MongoDB-Log	10.32.8.18	Supplier logs	4
MongoDB-Room	10.32.8.96	Room mappings	8.5M
MongoDB-Unmapped	10.32.8.101	Unmapped rooms	33K
MongoDB-APILog	10.32.8.75	API RQ/RS logs	162M
MongoDB-Perf	10.32.8.74	Supplier perf	216M

SQL Server Service Distribution¶

Database	IP:Port	Purpose	Endpoint Usage
withinearthUpdated	10.32.8.130:1988	Primary	All writes
withinearthUpdated	10.32.8.5:1433 (VIP)	Read replicas	All reads
Logtracking	10.32.8.152:1433	API logs	All
savesupplierlog	10.32.8.140:1988	Supplier logs	availability
ErrorLog	10.32.8.16:1433	Error logs	All errors
Derbysoftnew	10.32.8.142:1433	DerbySoft CM	CM endpoints

API Configuration¶

Timeouts¶

Component	Timeout	Purpose
HAProxy Client	90s	Client connection
HAProxy Server	120s	Backend response
Supplier Search	40s	Parallel supplier calls
Database	30s	SQL queries
MongoDB	10s	Cache operations
Redis	5s	Session/cache

Rate Limiting¶

Rate limiting is implemented at the HAProxy layer and managed via haproxy-ui.withinearth.com.

Per-Client Rate Limiting

Each client has their own individual rate limit applied ONLY to Search (/availability) endpoint. Rate limits are NOT shared between clients - each agent gets their own allocation.

Client Type	Rate Limit	Applied To
Standard Agent	50 req/s	Search only (per client)
Premium Agent	100-420 req/s	Search only (per client)
Enterprise	500+ req/s	Search only (per client)

Management:

Aspect	Details
Implementation	HAProxy stick-tables
Management UI	https://haproxy-ui.withinearth.com
Scope	Per-client, per-Search endpoint
Other Endpoints	No rate limiting (Book, Cancel, etc.)

Caching Strategy¶

Cache Layer	Technology	TTL	Purpose
Search Results	MongoDB	35 min	Reduce supplier calls
Session Data	Redis	60 min	User sessions
Static Data	Memory	24 hours	Countries, cities
Agent Config	Memory	15 min	Markup, settings

Monitoring & Observability¶

Health Endpoints¶

Endpoint	URL	Purpose
API Health	/api/xconnect/healthcheck	API server status
HAProxy Stats	http://10.32.8.36:45001/stats	Load balancer stats
Redis Cluster	http://10.32.8.209:8888/api/health	Redis cluster health

Key Metrics¶

Metric	Normal	Warning	Critical
Response Time	<2s	2-5s	>5s
Error Rate	<0.1%	0.1-1%	>1%
CPU Usage	<60%	60-80%	>80%
Memory Usage	<70%	70-85%	>85%
Queue Depth	<100	100-500	>500
Active Connections	<20K	20-30K	>30K

Monitoring Tools¶

Tool	Purpose	Access
Zabbix	Infrastructure monitoring	http://10.32.8.148/zabbix
UptimeKuma	Uptime monitoring	http://10.32.8.102:3001
HAProxy UI	Load balancer management	https://haproxy-ui.withinearth.com
Redis Monitor	Redis cluster status	http://10.32.8.209:8888

Security¶

Network Security¶

Layer	Protection
Perimeter	pfSense IDS/IPS
Application	HAProxy rate limiting, IP whitelisting
API Servers	WAN disabled, LAN only
Data	TLS 1.2+, encrypted connections

Authentication¶

Type	Method	Usage
Agent Auth	Token-based	All API calls
Supplier Auth	API Key/OAuth	Supplier calls
Admin Auth	Username/Password	Management

IP Whitelisting¶

6,199 whitelisted IPs in HAProxy
Automatic rejection of non-whitelisted IPs
Exception for Channel Manager endpoints

Performance Optimization¶

Current Optimizations¶

Optimization	Impact
Connection Pooling	-50% connection time
Result Caching	-70% supplier calls
Parallel Supplier Calls	-60% search time
Read Replicas	-80% primary DB load
Redis Clustering	+300% cache capacity

Recommended Improvements¶

Improvement	Expected Impact
Redis 3-Node Cluster	+99.9% cache availability
MongoDB Replica Sets	+99.9% cache reliability
API Response Compression	-40% bandwidth
GraphQL Endpoint	-30% over-fetching

Disaster Recovery¶

Backup Strategy¶

Component	Frequency	Retention	Location
SQL Primary	Every 2 hours	30 days	Local + Offsite
SQL Replicas	Transaction logs	Real-time	6 replicas
MongoDB	Daily	7 days	Local
Configuration	Every commit	Unlimited	Git

RTO/RPO¶

Component	RTO	RPO
Load Balancer	<1 min	0
API Servers	<5 min	0
SQL Database	<15 min	<5 min
Full System	<30 min	<15 min

Appendix: Quick Reference¶

API Server IPs¶

API-1: 10.32.8.134 (Ports: 19169-19211)
API-2: 10.32.8.135 (Ports: 19212-19254)
API-3: 10.32.8.139 (Ports: 19255-19297)
API-4: 10.32.8.137 (Ports: 19298-19340)
API-5: 10.32.8.35  (Ports: 19341-19383)
API-6: 10.32.8.166 (Ports: 19384-19426)
API-7: 10.32.8.167 (Ports: 19427-19635)

Database Connection Strings¶

Primary: 10.32.8.130:1988 (withinearthUpdated)
Replica VIP: 10.32.8.5:1433 (withinearthUpdated)
Logs: 10.32.8.152:1433 (Logtracking)
Supplier Logs: 10.32.8.140:1988 (savesupplierlog)

MongoDB Connections¶

Cache-1: mongodb://10.32.8.51:27017/
Cache-2: mongodb://10.32.8.52:27017/
Cache-3: mongodb://10.32.8.53:27017/
Room Mapping: mongodb://10.32.8.96:27017/
API Logs: mongodb://10.32.8.75:27017/
Performance: mongodb://10.32.8.74:27017/

Redis Connections¶

Master: 10.32.8.202:6379
Replica-1: 10.32.8.203:6379
Replica-2: 10.32.8.204:6379

Last Updated: 2025-12-02 Version: 1.0