Documentation

Best Practices

Copy page

This guide provides recommendations for building robust, efficient integrations with the SymTrain API.

---

Authentication

API Key Security

Do:

• ✅ Store API keys in environment variables or secure credential stores
• ✅ Use different keys for development, staging, and production
• ✅ Rotate keys periodically (every 90 days recommended)
• ✅ Restrict key access to authorized personnel only

Don't:

• ❌ Hard-code API keys in source code
• ❌ Commit keys to version control
• ❌ Share keys via email or messaging apps
• ❌ Use production keys in development

---

Rate Limiting

Limits

• 100 requests per 5 minutes per API key
• Exceeding limits returns 429 Too Many Requests

Strategies

1. Implement Exponential Backoff

Code
 
async function requestWithBackoff(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
    await new Promise((resolve) => setTimeout(resolve, delay));
  }

  throw new Error("Rate limit exceeded after retries");
}

2. Batch Operations

• Use bulk endpoints when available (e.g., /bulk-import)
• Group related requests when possible

3. Caching

• Cache simulation library data (updates infrequently)
• Cache organization/team data locally

---

Error Handling

HTTP Status Codes

Code	Meaning	Action
200	Success	Process response
400	Bad Request	Check request format
401	Unauthorized	Verify API key
404	Not Found	Verify resource ID
429	Rate Limited	Implement backoff
500	Server Error	Retry with backoff

Robust Error Handling Pattern

Code
 
async function safeApiRequest(url, options) {
  try {
    const response = await fetch(url, options);

    if (!response.ok) {
      const error = await response.json();

      switch (response.status) {
        case 400:
          console.error("Validation error:", error);
          break;
        case 401:
          console.error("Authentication failed - check API key");
          break;
        case 429:
          console.warn("Rate limited - retrying...");
          // Implement backoff
          break;
        case 500:
          console.error("Server error - retry later");
          break;
      }

      throw new Error(`API error: ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    console.error("Request failed:", error);
    throw error;
  }
}

---

Pagination

Large Result Sets

Always handle pagination for:

• User lists (if > 100 users)
• Reports (if > 100 records)
• Historical data queries

Pattern:

Code
 
async function getAllResults(endpoint, params) {
  let allData = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(endpoint, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ ...params, page, pageSize: 100 }),
    });

    const data = await response.json();
    allData = allData.concat(data.results);

    hasMore = data.results.length === data.pageSize;
    page++;
  }

  return allData;
}

---

Data Validation

Before Sending Requests

Date Ranges

• Validate maximum 3-month (180-day) span for reports
• Use ISO 8601 format: YYYY-MM-DD

CSV Files (Bulk Import)

• Validate row count ≤ 750
• Verify email === username
• Check role is "trainee"
• Validate status is ACTIVE or INACTIVE

IDs

• Verify organization ID exists
• Confirm user ID is valid before assignment
• Check simulation ID exists in library

---

Performance Optimization

1. Parallel Requests (When Possible)

Code
 
// Good: Parallel independent requests
const [simulations, users] = await Promise.all([
  getSimulations(orgId),
  getUsers(orgId),
]);

// Bad: Sequential when not needed
const simulations = await getSimulations(orgId);
const users = await getUsers(orgId);

2. Minimize Payload Size

• Request only needed fields
• Use appropriate page sizes (100 is optimal)

3. Connection Pooling

• Reuse HTTP connections when making multiple requests
• Use keep-alive headers

---

Token Management

User Access Tokens

• Lifespan: 1 hour
• Purpose: Single-use deep-links for simulation access
• Best Practice: Generate fresh tokens for each user session

Code
 
// Good: Generate token when needed
async function getSimulationLink(orgId, userId, simulationId) {
  const { token } = await generateToken(orgId, userId);
  return `https://symtrain.com/your-org-id/simulation/${simulationId}?token=${token}`;
}

// Bad: Storing tokens long-term
const token = await generateToken(orgId, userId);
await database.save({ userId, token }); // Don't do this!

---

Monitoring & Logging

What to Log

Essential:

• Request timestamps
• Response status codes
• Error messages

Optional:

• Request/response payloads (exclude sensitive data)
• Response times
• User IDs involved

Sample Logging

Code
 
async function loggedApiRequest(endpoint, options) {
  const startTime = Date.now();

  console.log(`[${new Date().toISOString()}] Request: ${endpoint}`);

  try {
    const response = await fetch(endpoint, options);
    const duration = Date.now() - startTime;

    console.log(
      `[${new Date().toISOString()}] Response: ${response.status} (${duration}ms)`
    );

    return response;
  } catch (error) {
    console.error(`[${new Date().toISOString()}] Error:`, error);
    throw error;
  }
}

---

Security Considerations

Data Protection

• Use HTTPS for all API requests (enforced by API)
• Validate and sanitize user input before sending to API
• Implement proper access controls in your application
• Don't expose API responses directly to end users

User Data

• Follow GDPR/privacy regulations
• Store minimal user data locally
• Implement data retention policies
• Secure transmission of user tokens

---

Testing

Recommended Testing Strategy

1. Unit Tests

• Validate request formatting
• Test error handling logic
• Verify pagination logic

2. Integration Tests

• Test against staging environment
• Verify complete workflows
• Test rate limit handling

3. Staging Environment

• Use separate API keys for testing
• Test with production-like data volumes
• Validate bulk operations

---

Common Pitfalls

Issue	Solution
Hitting rate limits frequently	Implement request batching and caching
Token expiration errors	Generate tokens just-in-time, not in advance
Pagination missing records	Always check hasMore or compare record counts
Date range errors	Validate 180-day maximum before request
CSV upload failures	Validate format client-side before upload

---

Next Steps

• API Reference - Complete endpoint documentation
• FAQ - Common questions

---

Need help? Contact support