CargoWise REST API vs eAdapter: When to Use Each (2025 Comparison)

Choosing between CargoWise REST API and eAdapter is one of the most critical decisions when designing freight forwarding software integrations. Each approach has distinct advantages, performance characteristics, and use cases that can significantly impact your integration's success, scalability, and maintainability.

This comprehensive comparison examines both integration methods in detail, providing clear guidance on when to use each approach. Whether you're building a new integration or evaluating existing systems, this guide will help you make informed decisions that align with your technical requirements and business objectives.

Understanding CargoWise Integration Options

CargoWise REST API Overview

The CargoWise REST API is a modern, HTTP-based integration interface that provides direct access to CargoWise functionality through standard REST principles. It offers synchronous communication with immediate responses and supports both JSON and XML data formats.

Key Characteristics:

• Synchronous: Immediate request-response pattern
• HTTP-based: Uses standard HTTP methods (GET, POST, PUT, DELETE)
• JSON/XML: Supports multiple data formats
• Real-time: Provides immediate data access
• Stateless: Each request is independent
• RESTful: Follows REST architectural principles

eAdapter Overview

eAdapter is CargoWise's traditional message-based integration framework that uses XML messages for asynchronous communication. It's designed for high-volume, reliable message processing with built-in error handling and retry mechanisms.

Key Characteristics:

• Asynchronous: Message-based communication with queuing
• XML-based: Uses XML message formats exclusively
• Reliable: Built-in retry and error handling
• High-volume: Designed for bulk data processing
• Message-oriented: Uses message queues and processing
• Enterprise-grade: Built for complex integration scenarios

Detailed Feature Comparison

Communication Patterns

REST API Communication:

// Synchronous request-response
public async Task<ShipmentData> GetShipment(string shipmentId)
{
    var response = await httpClient.GetAsync($"/api/shipments/{shipmentId}");
    response.EnsureSuccessStatusCode();
    
    var json = await response.Content.ReadAsStringAsync();
    return JsonSerializer.Deserialize<ShipmentData>(json);
}

// Immediate response
public async Task<ShipmentData> CreateShipment(CreateShipmentRequest request)
{
    var json = JsonSerializer.Serialize(request);
    var content = new StringContent(json, Encoding.UTF8, "application/json");
    
    var response = await httpClient.PostAsync("/api/shipments", content);
    response.EnsureSuccessStatusCode();
    
    var responseJson = await response.Content.ReadAsStringAsync();
    return JsonSerializer.Deserialize<ShipmentData>(responseJson);
}

eAdapter Communication:

// Asynchronous message processing
public async Task<string> SendShipmentMessage(UniversalShipmentMessage message)
{
    var xml = SerializeToXml(message);
    var response = await eAdapterClient.SendMessageAsync(xml);
    
    // Response may be delayed or require polling
    return response.MessageId;
}

// Message queuing and processing
public async Task ProcessBatchMessages(List<UniversalShipmentMessage> messages)
{
    var batchXml = CreateBatchXml(messages);
    var response = await eAdapterClient.SendBatchAsync(batchXml);
    
    // Process response asynchronously
    await ProcessBatchResponse(response);
}

Data Format Support

REST API Data Formats:

// JSON format (preferred)
{
  "shipmentId": "SH-2025-001",
  "mode": "Air",
  "origin": {
    "city": "New York",
    "country": "US",
    "airport": "JFK"
  },
  "destination": {
    "city": "London",
    "country": "GB",
    "airport": "LHR"
  },
  "cargo": {
    "description": "Electronics",
    "weight": 150.5,
    "volume": 2.3,
    "pieces": 5
  }
}

eAdapter Data Format:

<!-- XML format (required) -->
<UniversalShipment>
  <Header>
    <MessageId>MSG-2025-001</MessageId>
    <Timestamp>2025-01-19T10:00:00Z</Timestamp>
    <SourceSystem>ExternalSystem</SourceSystem>
  </Header>
  <Shipment>
    <ShipmentId>SH-2025-001</ShipmentId>
    <Mode>Air</Mode>
    <Origin>
      <City>New York</City>
      <Country>US</Country>
      <Airport>JFK</Airport>
    </Origin>
    <Destination>
      <City>London</City>
      <Country>GB</Country>
      <Airport>LHR</Airport>
    </Destination>
    <Cargo>
      <Description>Electronics</Description>
      <Weight>150.5</Weight>
      <Volume>2.3</Volume>
      <Pieces>5</Pieces>
    </Cargo>
  </Shipment>
</UniversalShipment>

Performance Characteristics

REST API Performance:

• Latency: Low (typically 100-500ms)
• Throughput: Moderate (100-1000 requests/second)
• Scalability: Good for moderate loads
• Resource Usage: Lower memory footprint
• Network: Standard HTTP overhead

eAdapter Performance:

• Latency: Higher (1-30 seconds for processing)
• Throughput: High (1000+ messages/second)
• Scalability: Excellent for high-volume processing
• Resource Usage: Higher memory usage for queuing
• Network: Optimized for bulk operations

Error Handling Approaches

REST API Error Handling:

public async Task<ApiResponse<ShipmentData>> GetShipmentWithErrorHandling(string shipmentId)
{
    try
    {
        var response = await httpClient.GetAsync($"/api/shipments/{shipmentId}");
        
        if (response.IsSuccessStatusCode)
        {
            var json = await response.Content.ReadAsStringAsync();
            var data = JsonSerializer.Deserialize<ShipmentData>(json);
            return ApiResponse<ShipmentData>.Success(data);
        }
        else
        {
            var errorJson = await response.Content.ReadAsStringAsync();
            var error = JsonSerializer.Deserialize<ApiError>(errorJson);
            return ApiResponse<ShipmentData>.Error(error.Message, (int)response.StatusCode);
        }
    }
    catch (HttpRequestException ex)
    {
        return ApiResponse<ShipmentData>.Error($"Network error: {ex.Message}", 0);
    }
    catch (TaskCanceledException ex)
    {
        return ApiResponse<ShipmentData>.Error($"Request timeout: {ex.Message}", 408);
    }
}

eAdapter Error Handling:

public async Task<eAdapterResponse> SendMessageWithErrorHandling(UniversalShipmentMessage message)
{
    try
    {
        var xml = SerializeToXml(message);
        var response = await eAdapterClient.SendMessageAsync(xml);
        
        if (response.IsSuccess)
        {
            return response;
        }
        else
        {
            // Handle specific error types
            switch (response.ErrorCode)
            {
                case "VALIDATION_ERROR":
                    return await HandleValidationError(response);
                case "SYSTEM_ERROR":
                    return await HandleSystemError(response);
                case "TIMEOUT_ERROR":
                    return await HandleTimeoutError(response);
                default:
                    return await HandleGenericError(response);
            }
        }
    }
    catch (eAdapterException ex)
    {
        _logger.LogError(ex, "eAdapter error: {Message}", ex.Message);
        return eAdapterResponse.Error(ex.Message);
    }
}

When to Use REST API

Ideal Use Cases

1. Real-Time Data Access

// Perfect for real-time queries
public async Task<ShipmentStatus> GetShipmentStatus(string shipmentId)
{
    var response = await httpClient.GetAsync($"/api/shipments/{shipmentId}/status");
    response.EnsureSuccessStatusCode();
    
    var json = await response.Content.ReadAsStringAsync();
    return JsonSerializer.Deserialize<ShipmentStatus>(json);
}

// Real-time tracking updates
public async Task<List<TrackingEvent>> GetTrackingEvents(string shipmentId)
{
    var response = await httpClient.GetAsync($"/api/shipments/{shipmentId}/tracking");
    response.EnsureSuccessStatusCode();
    
    var json = await response.Content.ReadAsStringAsync();
    return JsonSerializer.Deserialize<List<TrackingEvent>>(json);
}

2. Interactive Applications

// Web applications requiring immediate feedback
public async Task<ValidationResult> ValidateShipmentData(ShipmentData data)
{
    var json = JsonSerializer.Serialize(data);
    var content = new StringContent(json, Encoding.UTF8, "application/json");
    
    var response = await httpClient.PostAsync("/api/shipments/validate", content);
    response.EnsureSuccessStatusCode();
    
    var resultJson = await response.Content.ReadAsStringAsync();
    return JsonSerializer.Deserialize<ValidationResult>(resultJson);
}

3. Simple CRUD Operations

// Straightforward create, read, update, delete operations
public async Task<CustomerData> CreateCustomer(CreateCustomerRequest request)
{
    var json = JsonSerializer.Serialize(request);
    var content = new StringContent(json, Encoding.UTF8, "application/json");
    
    var response = await httpClient.PostAsync("/api/customers", content);
    response.EnsureSuccessStatusCode();
    
    var responseJson = await response.Content.ReadAsStringAsync();
    return JsonSerializer.Deserialize<CustomerData>(responseJson);
}

4. Mobile Applications

// Mobile apps requiring quick responses
public async Task<List<ShipmentSummary>> GetMyShipments(string customerId)
{
    var response = await httpClient.GetAsync($"/api/customers/{customerId}/shipments");
    response.EnsureSuccessStatusCode();
    
    var json = await response.Content.ReadAsStringAsync();
    return JsonSerializer.Deserialize<List<ShipmentSummary>>(json);
}

REST API Advantages

1. Immediate Response: Get data instantly without waiting
2. Simple Integration: Easy to implement with standard HTTP libraries
3. Real-time Capabilities: Perfect for live data and interactive applications
4. Standard Protocols: Uses familiar HTTP methods and status codes
5. Lightweight: Lower resource usage and network overhead
6. Debugging: Easy to test with tools like Postman or curl

REST API Limitations

1. Rate Limiting: Subject to API rate limits
2. Network Dependency: Requires stable network connection
3. Synchronous Only: No built-in queuing or retry mechanisms
4. Limited Bulk Operations: Not optimized for high-volume processing
5. Timeout Issues: Requests can timeout on slow networks

When to Use eAdapter

Ideal Use Cases

1. High-Volume Data Processing

// Perfect for bulk data operations
public async Task ProcessBulkShipments(List<ShipmentData> shipments)
{
    var messages = shipments.Select(s => new UniversalShipmentMessage
    {
        ShipmentId = s.Id,
        Mode = s.Mode,
        Origin = s.Origin,
        Destination = s.Destination,
        Cargo = s.Cargo
    }).ToList();
    
    var batchXml = CreateBatchXml(messages);
    await eAdapterClient.SendBatchAsync(batchXml);
}

2. Reliable Message Processing

// Guaranteed message delivery with retry logic
public async Task SendCriticalShipmentData(UniversalShipmentMessage message)
{
    var xml = SerializeToXml(message);
    
    // eAdapter handles retries automatically
    var response = await eAdapterClient.SendMessageAsync(xml);
    
    if (!response.IsSuccess)
    {
        // Message will be retried automatically
        _logger.LogWarning("Message {MessageId} failed, will be retried", message.MessageId);
    }
}

3. Complex Integration Scenarios

// Multi-step integration workflows
public async Task ProcessComplexWorkflow(WorkflowData workflow)
{
    // Step 1: Create shipment
    var shipmentMessage = CreateShipmentMessage(workflow.Shipment);
    await eAdapterClient.SendMessageAsync(SerializeToXml(shipmentMessage));
    
    // Step 2: Create consol
    var consolMessage = CreateConsolMessage(workflow.Consol);
    await eAdapterClient.SendMessageAsync(SerializeToXml(consolMessage));
    
    // Step 3: Create forward instructions
    var forwardMessage = CreateForwardMessage(workflow.Forward);
    await eAdapterClient.SendMessageAsync(SerializeToXml(forwardMessage));
}

4. Legacy System Integration

// Integrating with systems that use message queues
public async Task IntegrateWithLegacySystem(LegacySystemData data)
{
    var message = ConvertLegacyDataToUniversalShipment(data);
    var xml = SerializeToXml(message);
    
    // eAdapter handles the complexity of CargoWise integration
    await eAdapterClient.SendMessageAsync(xml);
}

eAdapter Advantages

1. Reliability: Built-in retry mechanisms and error handling
2. High Throughput: Optimized for bulk data processing
3. Message Queuing: Handles message ordering and persistence
4. Enterprise Features: Designed for complex integration scenarios
5. Asynchronous Processing: Non-blocking message processing
6. Scalability: Can handle very high message volumes

eAdapter Limitations

1. Complexity: More complex to implement and maintain
2. XML Only: Limited to XML message format
3. Asynchronous: No immediate response for real-time needs
4. Learning Curve: Requires understanding of message-based architecture
5. Debugging: More difficult to debug message processing issues
6. Resource Usage: Higher memory and processing requirements

Performance Comparison

Latency Comparison

REST API Latency:

• Simple Queries: 100-300ms
• Complex Queries: 300-1000ms
• Data Creation: 200-500ms
• Data Updates: 150-400ms

eAdapter Latency:

• Message Submission: 50-200ms
• Message Processing: 1-30 seconds
• Batch Processing: 5-60 seconds
• Error Handling: 2-10 seconds

Throughput Comparison

REST API Throughput:

• Single Requests: 100-500 requests/second
• Batched Requests: 200-1000 requests/second
• Concurrent Users: 50-200 users
• Data Volume: 1-10 MB/second

eAdapter Throughput:

• Single Messages: 500-2000 messages/second
• Batch Messages: 1000-5000 messages/second
• Concurrent Processing: 100-500 concurrent messages
• Data Volume: 10-100 MB/second

Resource Usage Comparison

REST API Resource Usage:

• Memory: 50-200 MB per instance
• CPU: Low to moderate usage
• Network: Standard HTTP overhead
• Storage: Minimal (stateless)

eAdapter Resource Usage:

• Memory: 200-1000 MB per instance
• CPU: Moderate to high usage
• Network: Optimized for bulk operations
• Storage: Message queue storage required

Implementation Decision Matrix

Use REST API When:

Use eAdapter When:

Hybrid Integration Strategies

Combining Both Approaches

Real-time + Bulk Processing:

public class HybridCargoWiseIntegration
{
    private readonly CargoWiseRestApiClient _restClient;
    private readonly eAdapterClient _eAdapterClient;
    
    public HybridCargoWiseIntegration(CargoWiseRestApiClient restClient, eAdapterClient eAdapterClient)
    {
        _restClient = restClient;
        _eAdapterClient = eAdapterClient;
    }
    
    // Use REST API for real-time queries
    public async Task<ShipmentStatus> GetShipmentStatus(string shipmentId)
    {
        return await _restClient.GetShipmentStatusAsync(shipmentId);
    }
    
    // Use eAdapter for bulk data processing
    public async Task ProcessBulkShipments(List<ShipmentData> shipments)
    {
        var messages = shipments.Select(CreateUniversalShipmentMessage).ToList();
        var batchXml = CreateBatchXml(messages);
        await _eAdapterClient.SendBatchAsync(batchXml);
    }
    
    // Use REST API for immediate validation
    public async Task<ValidationResult> ValidateShipmentData(ShipmentData data)
    {
        return await _restClient.ValidateShipmentAsync(data);
    }
    
    // Use eAdapter for reliable data submission
    public async Task SubmitShipmentData(ShipmentData data)
    {
        var message = CreateUniversalShipmentMessage(data);
        var xml = SerializeToXml(message);
        await _eAdapterClient.SendMessageAsync(xml);
    }
}

Smart Routing Strategy

Route Based on Operation Type:

public class SmartCargoWiseRouter
{
    private readonly CargoWiseRestApiClient _restClient;
    private readonly eAdapterClient _eAdapterClient;
    
    public async Task<IntegrationResponse> ProcessRequest(IntegrationRequest request)
    {
        switch (request.OperationType)
        {
            case OperationType.Query:
            case OperationType.Validation:
            case OperationType.RealTimeUpdate:
                return await ProcessWithRestApi(request);
            
            case OperationType.BulkCreate:
            case OperationType.BulkUpdate:
            case OperationType.BulkDelete:
                return await ProcessWithEAdapter(request);
            
            case OperationType.ComplexWorkflow:
                return await ProcessWithEAdapter(request);
            
            default:
                throw new ArgumentException($"Unknown operation type: {request.OperationType}");
        }
    }
    
    private async Task<IntegrationResponse> ProcessWithRestApi(IntegrationRequest request)
    {
        // Use REST API for immediate response
        var response = await _restClient.ProcessRequestAsync(request);
        return new IntegrationResponse
        {
            Success = true,
            Data = response.Data,
            ResponseTime = response.ResponseTime,
            Method = "REST API"
        };
    }
    
    private async Task<IntegrationResponse> ProcessWithEAdapter(IntegrationRequest request)
    {
        // Use eAdapter for reliable processing
        var message = ConvertToEAdapterMessage(request);
        var response = await _eAdapterClient.SendMessageAsync(SerializeToXml(message));
        
        return new IntegrationResponse
        {
            Success = response.IsSuccess,
            MessageId = response.MessageId,
            Method = "eAdapter"
        };
    }
}

Migration Strategies

From eAdapter to REST API

Gradual Migration Approach:

public class CargoWiseMigrationService
{
    private readonly eAdapterClient _legacyClient;
    private readonly CargoWiseRestApiClient _newClient;
    private readonly bool _useNewApi;
    
    public async Task<IntegrationResponse> ProcessRequest(IntegrationRequest request)
    {
        if (_useNewApi && IsRestApiSuitable(request))
        {
            try
            {
                return await ProcessWithRestApi(request);
            }
            catch (Exception ex)
            {
                _logger.LogWarning(ex, "REST API failed, falling back to eAdapter");
                return await ProcessWithEAdapter(request);
            }
        }
        else
        {
            return await ProcessWithEAdapter(request);
        }
    }
    
    private bool IsRestApiSuitable(IntegrationRequest request)
    {
        return request.OperationType == OperationType.Query ||
               request.OperationType == OperationType.Validation ||
               request.OperationType == OperationType.RealTimeUpdate;
    }
}

From REST API to eAdapter

Performance-Based Migration:

public class CargoWisePerformanceMigration
{
    private readonly CargoWiseRestApiClient _restClient;
    private readonly eAdapterClient _eAdapterClient;
    private readonly PerformanceMonitor _monitor;
    
    public async Task<IntegrationResponse> ProcessRequest(IntegrationRequest request)
    {
        // Monitor performance and migrate high-volume operations
        if (ShouldUseEAdapter(request))
        {
            return await ProcessWithEAdapter(request);
        }
        else
        {
            return await ProcessWithRestApi(request);
        }
    }
    
    private bool ShouldUseEAdapter(IntegrationRequest request)
    {
        var metrics = _monitor.GetMetrics(request.OperationType);
        
        return metrics.RequestsPerSecond > 100 ||
               metrics.AverageResponseTime > 1000 ||
               metrics.ErrorRate > 0.05;
    }
}

Best Practices for Each Approach

REST API Best Practices

1. Implement Proper Error Handling:

public class CargoWiseRestApiClient
{
    public async Task<T> ExecuteWithErrorHandling<T>(Func<Task<T>> operation)
    {
        try
        {
            return await operation();
        }
        catch (HttpRequestException ex)
        {
            _logger.LogError(ex, "Network error occurred");
            throw new CargoWiseNetworkException("Network error", ex);
        }
        catch (TaskCanceledException ex)
        {
            _logger.LogError(ex, "Request timeout occurred");
            throw new CargoWiseTimeoutException("Request timeout", ex);
        }
        catch (HttpRequestException ex) when (ex.Message.Contains("401"))
        {
            _logger.LogError(ex, "Authentication failed");
            throw new CargoWiseAuthenticationException("Authentication failed", ex);
        }
    }
}

2. Use Connection Pooling:

public class CargoWiseRestApiClient
{
    private readonly HttpClient _httpClient;
    
    public CargoWiseRestApiClient(HttpClient httpClient)
    {
        _httpClient = httpClient;
        
        // Configure connection pooling
        _httpClient.DefaultRequestHeaders.Add("Connection", "keep-alive");
        _httpClient.Timeout = TimeSpan.FromSeconds(30);
    }
}

3. Implement Rate Limiting:

public class CargoWiseRateLimiter
{
    private readonly SemaphoreSlim _semaphore;
    private readonly int _maxConcurrentRequests;
    
    public CargoWiseRateLimiter(int maxConcurrentRequests = 10)
    {
        _maxConcurrentRequests = maxConcurrentRequests;
        _semaphore = new SemaphoreSlim(maxConcurrentRequests, maxConcurrentRequests);
    }
    
    public async Task<T> ExecuteWithRateLimit<T>(Func<Task<T>> operation)
    {
        await _semaphore.WaitAsync();
        
        try
        {
            return await operation();
        }
        finally
        {
            _semaphore.Release();
        }
    }
}

eAdapter Best Practices

1. Implement Message Validation:

public class eAdapterMessageValidator
{
    public ValidationResult ValidateMessage(string xmlMessage, string messageType)
    {
        try
        {
            var doc = XDocument.Parse(xmlMessage);
            var schema = GetSchema(messageType);
            
            doc.Validate(schema, (sender, e) =>
            {
                throw new ValidationException($"Schema validation error: {e.Message}");
            });
            
            return ValidationResult.Success();
        }
        catch (XmlException ex)
        {
            return ValidationResult.Error($"XML parsing error: {ex.Message}");
        }
        catch (ValidationException ex)
        {
            return ValidationResult.Error($"Validation error: {ex.Message}");
        }
    }
}

2. Use Message Batching:

public class eAdapterMessageBatcher
{
    private readonly List<eAdapterMessage> _pendingMessages;
    private readonly int _batchSize;
    private readonly Timer _batchTimer;
    
    public eAdapterMessageBatcher(int batchSize = 100, TimeSpan batchTimeout = TimeSpan.FromSeconds(30))
    {
        _batchSize = batchSize;
        _pendingMessages = new List<eAdapterMessage>();
        _batchTimer = new Timer(ProcessBatch, null, batchTimeout, Timeout.InfiniteTimeSpan);
    }
    
    public async Task AddMessage(eAdapterMessage message)
    {
        lock (_pendingMessages)
        {
            _pendingMessages.Add(message);
            
            if (_pendingMessages.Count >= _batchSize)
            {
                _ = Task.Run(ProcessBatch);
            }
        }
    }
}

3. Implement Circuit Breaker:

public class eAdapterCircuitBreaker
{
    private readonly int _failureThreshold;
    private readonly TimeSpan _timeout;
    private int _failureCount;
    private DateTime _lastFailureTime;
    private CircuitState _state = CircuitState.Closed;
    
    public async Task<T> Execute<T>(Func<Task<T>> operation)
    {
        if (_state == CircuitState.Open)
        {
            if (DateTime.UtcNow - _lastFailureTime > _timeout)
            {
                _state = CircuitState.HalfOpen;
            }
            else
            {
                throw new CircuitBreakerOpenException("Circuit breaker is open");
            }
        }
        
        try
        {
            var result = await operation();
            OnSuccess();
            return result;
        }
        catch (Exception ex)
        {
            OnFailure();
            throw;
        }
    }
}

Conclusion

Choosing between CargoWise REST API and eAdapter depends on your specific requirements, performance needs, and integration complexity. Both approaches have their place in modern freight forwarding software integrations, and the best solution often involves using both strategically.

Key Decision Factors:

1. Real-time Requirements: Use REST API for immediate responses
2. Volume Processing: Use eAdapter for high-volume operations
3. Reliability Needs: Use eAdapter for guaranteed message delivery
4. Integration Complexity: Use eAdapter for complex workflows
5. Development Speed: Use REST API for rapid prototyping

Recommended Approach:

• Start with REST API for most integrations due to its simplicity
• Migrate to eAdapter for high-volume or complex scenarios
• Use hybrid approach for comprehensive solutions
• Monitor performance and adjust strategy based on metrics

Next Steps:

1. Evaluate your requirements against the decision matrix
2. Start with REST API for initial implementation
3. Monitor performance and identify bottlenecks
4. Consider eAdapter for high-volume operations
5. Implement hybrid approach for optimal results

For more CargoWise integration guidance and implementation support, explore our CargoWise Integration Services or contact our team for personalized consulting.

FAQ

Q: Can I use both REST API and eAdapter in the same application? A: Yes, many applications use both approaches strategically. Use REST API for real-time operations and eAdapter for bulk processing or complex workflows.

Q: Which approach is better for mobile applications? A: REST API is generally better for mobile applications due to its lower latency and simpler implementation. eAdapter is better suited for server-side bulk operations.

Q: How do I migrate from eAdapter to REST API? A: Start by identifying operations that can benefit from real-time responses, implement REST API for those operations, and gradually migrate other operations based on performance requirements.

Q: What are the performance implications of each approach? A: REST API has lower latency but limited throughput, while eAdapter has higher latency but much higher throughput. Choose based on your specific performance requirements.

Q: Which approach is more cost-effective? A: REST API is generally more cost-effective for low to moderate volume operations, while eAdapter becomes more cost-effective for high-volume operations due to its efficiency.