One method for retrieving data from MasonHub is through periodic polling using GET API calls. This approach gives your ERP system control over when and how frequently to check for updates.

​
Overview

Polling involves making scheduled GET requests to MasonHub’s API endpoints to retrieve the latest information about orders, shipments, inventory, and other business data.

Advantages

  • Full control over polling frequency
  • Simpler implementation
  • Better for batch processing
  • No firewall configuration needed

Considerations

  • May not be real-time
  • Higher API call volume
  • Need to manage polling frequency
  • Potential for missed updates

​
Common GET Endpoints

​
Order Data

​
Shipment Data

​
Polling Implementation Patterns

​
Time-Based Polling

Query for data updated since your last poll:

# Get orders updated in the last 5 minutes
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.masonhub.co/api/v1/orders?updated_since=2024-01-01T10:30:00Z"

​
Status-Based Polling

Focus on specific statuses that require action:

# Get orders that are ready to ship
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.masonhub.co/api/v1/orders?status=ready_to_ship"

​
Pagination Handling

Handle large datasets with pagination:

# First page
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.masonhub.co/api/v1/orders?limit=100&offset=0"

# Subsequent pages
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.masonhub.co/api/v1/orders?limit=100&offset=100"

Order Status Updates

  • Frequency: Every 2-5 minutes
  • Use case: Critical order tracking
  • Data: Order status changes, fulfillment updates

​
Error Handling & Retry Logic

​
Rate Limiting

Respect API rate limits to avoid service interruption. Implement exponential backoff for retries.

import time
import requests

def poll_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.get(url, headers=headers)
            
            if response.status_code == 429:  # Rate limited
                wait_time = 2 ** attempt  # Exponential backoff
                time.sleep(wait_time)
                continue
                
            return response
            
        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise e
            time.sleep(2 ** attempt)

​
Data Consistency

Implement mechanisms to ensure you don’t miss data:

1

Track Last Poll Time

Store the timestamp of your last successful poll

2

Use Updated Since Filter

Query for data updated since your last poll

3

Handle Gaps

If polling fails, extend the time window on the next attempt

4

Validate Data

Check for missing data and implement catch-up mechanisms

​
Monitoring & Observability

​
Key Metrics to Track

API Performance

  • Response times
  • Success rates
  • Error rates
  • Rate limit hits

Data Quality

  • Records processed
  • Data freshness
  • Missing data detection
  • Duplicate handling

​
Logging Best Practices

Log the following information for troubleshooting:

{
  "timestamp": "2024-01-01T10:30:00Z",
  "endpoint": "/orders",
  "query_params": {
    "updated_since": "2024-01-01T10:25:00Z",
    "limit": 100
  },
  "response_code": 200,
  "records_returned": 15,
  "processing_time_ms": 250
}

​
Integration Examples

​
Simple Polling Script

import requests
import time
from datetime import datetime, timedelta

class MasonHubPoller:
    def __init__(self, api_token, base_url):
        self.headers = {
            'Authorization': f'Bearer {api_token}',
            'Content-Type': 'application/json'
        }
        self.base_url = base_url
        
    def poll_orders(self, last_poll_time):
        url = f"{self.base_url}/orders"
        params = {
            'updated_since': last_poll_time.isoformat(),
            'limit': 100
        }
        
        response = requests.get(url, headers=self.headers, params=params)
        response.raise_for_status()
        
        return response.json()

​
Batch Processing

def process_order_updates():
    poller = MasonHubPoller(api_token, base_url)
    last_poll = get_last_poll_time()  # From your database
    
    orders = poller.poll_orders(last_poll)
    
    for order in orders.get('data', []):
        update_erp_order(order)
        
    save_last_poll_time(datetime.utcnow())

​
Performance Optimization

​
Reduce API Calls

​
Next Steps

Consider implementing callback events (webhooks) for real-time updates on critical data, while using polling for less time-sensitive information.

ConfigurationCallback Events (Webhooks)