Tracing API requests with Request-Id

Use Request-Id and Correlation-Id headers to trace, debug, and correlate Straddle API requests across services for faster troubleshooting and support.

Request ID and Correlation ID are powerful header tools for debugging and tracing API requests in Straddle. This guide will explain what they are, how to use them, and best practices for implementation.

What are Request ID and Correlation ID?

Request ID

A Request ID is a user-defined identifier in the header of each API request. It helps in tracking and debugging individual API calls.

Correlation ID

A Correlation ID is a user-defined identifier in the header of each API request. It helps in tracing a sequence of operations across multiple systems or services.

How to Use Request ID and Correlation ID

You can include Request ID and Correlation ID in your API requests to Straddle by adding specific headers to your HTTP requests.

Using Request ID and Correlation ID

Here’s an example of creating a charge using the correct fields as specified in the OpenAPI schema, along with Request ID and Correlation ID:

cURL

curl https://sandbox.straddle.com/v1/charges \
  -H "Authorization: Bearer 51NBBbbDBkrcnHrnR0nBGsOvFHQrM0n8T1FKZmAUWbJqq8oRsAM3dEZzBIbHwzKrVUUFOyRvX1Ib8Sn3VWWQMW00r300IIrGBWb1" \
  -H "Request-Id: req_1234567890" \
  -H "Correlation-Id: corr_abcdefghij" \
  -d paykey="pk_test_TYooMQauvdEDq54NiTphI7jx" \
  -d description="Example charge" \
  -d amount=1000 \
  -d currency="usd" \
  -d payment_date="2023-09-15" \
  -d consent_type="internet" \
  -d "device[ip_address]=192.168.1.1" \
  -d external_id="order_12345" \
  -d "config[balance_check]=required"

Here’s an example of creating a customer:

cURL

curl https://sandbox.straddle.com/v1/customers \
  -H "Authorization: Bearer 51NBBbbDBkrcnHrnR0nBGsOvFHQrM0n8T1FKZmAUWbJqq8oRsAM3dEZzBIbHwzKrVUUFOyRvX1Ib8Sn3VWWQMW00r300IIrGBWb1" \
  -H "Request-Id: req_0987654321" \
  -H "Correlation-Id: corr_klmnopqrst" \
  -d name="John Doe" \
  -d type="individual" \
  -d email="[e-mail]" \
  -d "address[address1]=123 Main St" \
  -d "address[city]=Anytown" \
  -d "address[state]=CA" \
  -d "address[zip]=12345" \
  -d phone="[phone]" \
  -d external_id="cust_12345" \
  -d "device[ip_address]=192.168.1.1" \
  -d "metadata[customer_group]=premium"

Retrieving Request ID and Correlation ID

Straddle includes the Request ID and Correlation ID (if provided) in the response headers of every API request.

• Request ID: Request-Id
• Correlation ID: Correlation-Id

You can retrieve these headers from the API response to log them or use them for debugging purposes.

Best Practices

1. Generate Unique IDs: Ensure that your Request IDs and Correlation IDs are unique. UUIDs are a good choice for this.

2. Consistent Usage: Use Request IDs for every API call, and use Correlation IDs for all requests related to a single operation or transaction.

3. Logging: Log both Request IDs and Correlation IDs in your application logs. This will make it easier to trace requests across your systems and Straddle.

4. Error Handling: Include the Request ID and Correlation ID when logging errors or exceptions. This will help in debugging issues more effectively.

5. Support Communication: When contacting Straddle support about a specific API request, always include the Request ID and Correlation ID (if applicable).

Implementation Example

Here’s an example of how you might implement Request ID and Correlation ID in a real-world scenario:

Node.js

const Straddle = require('straddle');
const { v4: uuidv4 } = require('uuid');

const straddle = new Straddle('51NBBbbDBkrcnHrnR0nBGsOvFHQrM0n8T1FKZmAUWbJqq8oRsAM3dEZzBIbHwzKrVUUFOyRvX1Ib8Sn3VWWQMW00r300IIrGBWb1');

async function processOrder(orderDetails) {
  const correlationId = uuidv4();
  
  try {
    // Create customer
    const customer = await straddle.customers.create({
      name: orderDetails.name,
      type: 'individual',
      email: orderDetails.email,
      phone: orderDetails.phone,
      external_id: orderDetails.customerId,
      device: {
        ip_address: orderDetails.ipAddress
      }
    }, {
      headers: {
        'Correlation-Id': correlationId,
        'Request-Id': uuidv4()
      }
    });

    // Create charge
    const charge = await straddle.charges.create({
      paykey: orderDetails.paykey,
      amount: orderDetails.amount,
      currency: orderDetails.currency,
      payment_date: new Date().toISOString().split('T')[0], // Today's date
      consent_type: 'internet',
      device: {
        ip_address: orderDetails.ipAddress
      },
      external_id: orderDetails.orderId
    }, {
      headers: {
        'Correlation-Id': correlationId,
        'Request-Id': uuidv4()
      }
    });

    console.log(`Order processed successfully. Charge ID: ${charge.id}`);
  } catch (error) {
    console.error(`Error processing order. Correlation ID: ${correlationId}`, error);
  }
}

processOrder({
  name: 'Jane Smith',
  email: '[e-mail]',
  phone: '[phone]',
  customerId: 'cust_67890',
  ipAddress: '192.168.1.1',
  amount: 2000,
  currency: 'usd',
  paykey: 'TYooMQauvdEDq54NiTphI7jx',
  orderId: 'order_54321'
});

In this example, we generate a unique Correlation ID for the entire order processing operation, and unique Request IDs for each API call. This allows us to trace the entire order process across multiple API calls.

Conclusion

Using Request ID and Correlation ID effectively can significantly improve your ability to debug and trace API requests when integrating with Straddle. By implementing these best practices, you’ll be better equipped to monitor your integration, troubleshoot issues, and communicate effectively with Straddle support when needed.

For more information on how Request ID and Correlation ID behave with specific API endpoints, refer to our API Reference documentation.