Getting Started

Best Practices

API Best Practices

Follow these guidelines to ensure optimal performance and reliability when integrating with the GG365 Golf API.

Implementing Webhook Handling

Webhooks provide real-time updates about booking status changes. Properly implementing webhook handling ensures your system stays in sync with the GG365 platform.

Webhook Setup

1. Register your webhook endpoint in your GG365 account dashboard
2. Implement HTTPS for your webhook endpoint (required for security)
3. Set up verification using the webhook secret

Example Webhook Handler

Code
 
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature));
}

app.post('/webhooks/golf-bookings', (req, res) => {
  const signature = req.headers['x-gg-signature'];
  
  // Verify the webhook signature
  if (!verifyWebhookSignature(JSON.stringify(req.body), signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = req.body;
  
  switch (event.type) {
    case 'booking.confirmed':
      // Handle booking confirmation
      updateBookingStatus(event.data.bookingId, 'confirmed');
      break;
    case 'booking.cancelled':
      // Handle booking cancellation
      updateBookingStatus(event.data.bookingId, 'cancelled');
      break;
    case 'booking.modified':
      // Handle booking modification
      syncBookingDetails(event.data.bookingId);
      break;
  }
  
  // Acknowledge receipt of the webhook
  res.status(200).send('Webhook received');
});

Webhook Event Types

Event Type	Description
booking.confirmed	Booking has been confirmed by the golf course
booking.cancelled	Booking has been cancelled
booking.modified	Booking details have been modified
tee_time.changed	Tee time has been changed for a booking
payment.received	Payment has been received for a booking
refund.processed	Refund has been processed for a cancelled booking

Caching Strategies

Implementing proper caching reduces API calls and improves performance.

What to Cache

Data	TTL	Notes
Course details	24 hours	Basic course information rarely changes
Course lists	12 hours	New courses are not added frequently
Pricing information	24 hours	May change seasonally, but not daily
Tee time availability	5 minutes	Refresh frequently as availability changes
Booking details	1 hour	May be modified or cancelled

Implementation Example

Code
 
const cache = new Map();

async function getCachedCourseDetails(courseId) {
  const cacheKey = `course_${courseId}`;
  const now = Date.now();
  
  if (cache.has(cacheKey)) {
    const cached = cache.get(cacheKey);
    if (now - cached.timestamp < 24 * 60 * 60 * 1000) {
      return cached.data;
    }
  }
  
  // Cache miss or expired
  const courseDetails = await api.getCourseDetails(courseId);
  cache.set(cacheKey, {
    data: courseDetails,
    timestamp: now
  });
  
  return courseDetails;
}

Error Handling and Retries

Robust error handling ensures your integration remains reliable even when issues occur.

Retry Strategy for Transient Errors

Code
 
async function makeApiCallWithRetries(apiCall, maxRetries = 3) {
  let retries = 0;
  
  while (retries < maxRetries) {
    try {
      return await apiCall();
    } catch (error) {
      // Don't retry if the error is client-side
      if (error.status >= 400 && error.status < 500) {
        // Client error (4xx)
        if (error.status === 429) {
          // Rate limit exceeded - wait before retrying
          const retryAfter = error.data.error.details.retryAfter || 1;
          await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
          retries++;
          continue;
        }
        
        // Don't retry other client errors
        throw error;
      }
      
      // Server error (5xx) - retry with exponential backoff
      if (retries === maxRetries - 1) {
        throw error; // Last retry failed
      }
      
      const delay = Math.pow(2, retries) * 1000 + Math.random() * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
      retries++;
    }
  }
}

Optimizing API Usage

Batch Operations

Where possible, use batch operations instead of making multiple API calls.

Example: Checking availability for multiple dates

Code
 
// Good - Use the date range endpoint
const dateRange = await api.getAvailabilityDateRange({
  courseId: 'course_123',
  startDate: '2023-07-01',
  endDate: '2023-07-10'
});

// Avoid - Making separate calls for each date
const dates = [];
for (let i = 1; i <= 10; i++) {
  const date = `2023-07-${i.toString().padStart(2, '0')}`;
  // Don't do this
  const availability = await api.getTeeTimeAvailability({
    courseId: 'course_123',
    date
  });
  dates.push(availability);
}

Pagination

When retrieving large lists, use pagination parameters effectively.

Code
 
// Fetch all bookings page by page
async function getAllBookings() {
  let page = 1;
  const limit = 100;
  let allBookings = [];
  let hasMore = true;
  
  while (hasMore) {
    const response = await api.getBookings({
      page,
      limit,
      startDate: '2023-01-01'
    });
    
    allBookings = [...allBookings, ...response.data];
    
    hasMore = response.pagination.currentPage < response.pagination.totalPages;
    page++;
  }
  
  return allBookings;
}

Handling Course-Specific Logic

Different golf courses may have different booking rules and requirements.

Check Course Booking Type

Always check if a course supports online booking before attempting to book:

Code
 
async function createBookingFlow(courseId, bookingData) {
  // Get course details first
  const course = await api.getCourseDetails(courseId);
  
  if (course.booking.isOnline) {
    // Online booking flow
    const teeTime = await api.getTeeTimeAvailability({
      courseId,
      date: bookingData.date
    });
    
    // Check if the requested time is available
    const isAvailable = teeTime.availableTimes.some(t => 
      t.time === bookingData.teeTime && t.available >= bookingData.players
    );
    
    if (isAvailable) {
      return await api.createBooking(bookingData);
    } else {
      throw new Error('Requested tee time is not available');
    }
  } else {
    // Offline booking flow
    return await api.createOfflineBookingRequest(bookingData);
  }
}

Security Best Practices

API Key Management

• Store API keys securely in environment variables or a secure vault
• Never expose API keys in client-side code
• Rotate API keys periodically
• Use different API keys for development and production

Protecting User Data

• Only collect and send the minimum player information required
• Use HTTPS for all API communications
• Implement proper access controls for booking data in your system

Testing Your Integration

Test Environment

Use our sandbox environment for testing before moving to production:

Code
 
Base URL: https://api-sandbox.golfglobe365.com/v1

Test Courses

Course ID	Description	Booking Type
test_course_online	Test course with online booking	online
test_course_offline	Test course with offline booking	offline
test_course_error	Test course that simulates errors	online

Monitoring and Logging

What to Log

• All API requests and responses (excluding sensitive data)
• Error responses with requestIds
• Webhook events received
• Booking status changes

Monitoring Best Practices

• Set up alerts for unusually high error rates
• Monitor rate limit usage to avoid hitting limits
• Track booking conversion rates (searches to bookings)
• Monitor webhook delivery success rates