Best Practices

This guide provides best practices for building high-quality, successful resources and scripts on the Mirra Store. Following these guidelines improves reliability, user satisfaction, and marketplace success.

Resource Development

API Design

Use RESTful conventions for consistent, predictable APIs:

GET for reading data
POST for creating resources
PUT or PATCH for updating existing resources
DELETE for removing resources
Return appropriate HTTP status codes (200, 201, 400, 404, 500)

Return consistent JSON structures:

{
  "status": "success",
  "data": {
    "temperature": 15.5,
    "conditions": "partly cloudy"
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "units": "celsius"
  }
}

Provide clear, actionable error messages:

{
  "status": "error",
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The 'city' parameter is required",
    "details": {
      "parameter": "city",
      "expected": "string",
      "received": "undefined"
    }
  }
}

Version your API to manage changes safely:

✅ Use URL versioning: /v1/weather, /v2/weather
✅ Maintain backwards compatibility within versions
✅ Deprecate old versions gracefully with advance notice
✅ Document all breaking changes clearly
❌ Don't make breaking changes without version increments

Documentation

Write clear, comprehensive instructions:

Explain what your resource does and why users need it
List all requirements and prerequisites
Provide step-by-step setup instructions
Include troubleshooting sections for common issues
Keep documentation updated with code changes

Include practical code examples:

// Example: Get current weather for a city
const response = await fetch('/v1/weather/current?city=London&units=metric');
const data = await response.json();
 
console.log(data.data.temperature); // 15.5
console.log(data.data.conditions);  // "partly cloudy"

Document all parameters thoroughly:

Parameter	Type	Required	Description	Default
`city`	string	Yes	City name (e.g., "London", "New York")	-
`units`	string	No	Temperature units: `"metric"` or `"imperial"`	`"metric"`
`lang`	string	No	Response language code (e.g., `"en"`, `"es"`)	`"en"`

Explain all error codes:

Error Code	Cause	Solution
`INVALID_PARAMETER`	Required parameter missing or invalid	Check parameter spelling and type
`CITY_NOT_FOUND`	City name not recognized	Verify city name spelling
`RATE_LIMIT_EXCEEDED`	Too many requests	Wait before retrying
`API_KEY_INVALID`	Authentication failed	Check API key configuration

Performance

Optimize response times:

✅ Target under 200ms for simple requests
✅ Use caching for frequently requested data
✅ Minimize database queries with proper indexing
✅ Optimize algorithms and data structures
❌ Don't perform expensive operations synchronously

Implement intelligent caching:

// Cache frequently requested data with TTL
const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
 
function getCachedData(key) {
  const cached = cache.get(key);
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
  return null;
}
 
function setCachedData(key, data) {
  cache.set(key, {
    data: data,
    timestamp: Date.now()
  });
}

Monitor and optimize performance:

Track response times for all endpoints
Identify and optimize slow operations
Set up alerts for performance degradation
Scale infrastructure as usage grows
Profile code to find bottlenecks

Security

Use HTTPS exclusively:

✅ Enforce TLS 1.2 or higher
✅ Use valid SSL/TLS certificates
✅ Redirect all HTTP requests to HTTPS
❌ Never transmit sensitive data over HTTP

Validate all inputs rigorously:

function validateCity(city) {
  // Check type and presence
  if (!city || typeof city !== 'string') {
    throw new Error('City parameter must be a non-empty string');
  }
  
  // Check length constraints
  if (city.length > 100) {
    throw new Error('City name exceeds maximum length of 100 characters');
  }
  
  // Validate format
  if (!/^[a-zA-Z\s\-']+$/.test(city)) {
    throw new Error('City name contains invalid characters');
  }
  
  return city.trim();
}

Implement rate limiting:

{
  "rateLimit": {
    "requests": 1000,
    "window": "1h",
    "strategy": "sliding-window"
  }
}

Support secure credential management:

✅ Support API key rotation without downtime
✅ Allow multiple active keys per user
✅ Implement key expiration policies
✅ Log all API key usage for auditing
❌ Never log or expose API keys in responses

Script Development

Code Quality

Write clean, readable code:

// ✅ Good: Clear and readable
function calculateAverage(numbers) {
  if (!numbers || numbers.length === 0) {
    return 0;
  }
  const sum = numbers.reduce((total, num) => total + num, 0);
  return sum / numbers.length;
}
 
// ❌ Bad: Unclear and complex
function calc(n) {
  return n.reduce((a,b)=>a+b,0)/n.length;
}

Add helpful documentation:

/**
 * Analyzes text and returns statistical information
 * 
 * @param {string} text - The input text to analyze
 * @returns {Object} Statistics including word count, sentence count, and average word length
 * @throws {Error} If text is not a string or is empty
 * 
 * @example
 * const stats = analyzeText("Hello world. This is a test.");
 * console.log(stats.wordCount); // 6
 */
function analyzeText(text) {
  if (typeof text !== 'string' || text.trim().length === 0) {
    throw new Error('Text must be a non-empty string');
  }
  
  // Split into words, filtering empty strings
  const words = text.split(/\s+/).filter(word => word.length > 0);
  
  // Count sentences by splitting on punctuation
  const sentences = text.split(/[.!?]+/).filter(s => s.trim().length > 0);
  
  // Calculate average word length
  const totalChars = words.reduce((sum, word) => sum + word.length, 0);
  const avgWordLength = words.length > 0 ? totalChars / words.length : 0;
  
  return {
    wordCount: words.length,
    sentenceCount: sentences.length,
    averageWordLength: avgWordLength.toFixed(2)
  };
}

Use meaningful, descriptive names:

// ✅ Good: Clear intent
const userCount = users.length;
const isValidEmail = validateEmail(emailAddress);
const processedResults = processData(inputData);
 
// ❌ Bad: Unclear abbreviations
const uc = users.length;
const x = validateEmail(emailAddress);
const pr = processData(inputData);

Performance

Optimize algorithm complexity:

// ✅ Good: O(n) - single pass
function findMaximum(numbers) {
  return Math.max(...numbers);
}
 
// ❌ Bad: O(n²) - unnecessary nested loops
function findMaximum(numbers) {
  let max = numbers[0];
  for (let i = 0; i < numbers.length; i++) {
    for (let j = 0; j < numbers.length; j++) {
      if (numbers[j] > max) {
        max = numbers[j];
      }
    }
  }
  return max;
}

Use efficient data structures:

// ✅ Good: Use Map for O(1) lookups
const userMap = new Map(users.map(user => [user.id, user]));
const user = userMap.get(userId); // O(1) lookup
 
// ❌ Bad: Array search is O(n)
const user = users.find(u => u.id === userId); // O(n) lookup

Avoid unnecessary computation:

// ✅ Good: Early return pattern
function processData(data) {
  if (!data || data.length === 0) {
    return [];
  }
  // Process data only if needed
  return data.map(item => transform(item));
}
 
// ❌ Bad: Perform work before validation
function processData(data) {
  const processed = data.map(item => expensiveTransform(item));
  if (!data || data.length === 0) {
    return [];
  }
  return processed;
}

Error Handling

Catch and handle all exceptions:

async function execute(params) {
  try {
    // Validate inputs
    validateParams(params);
    
    // Execute main logic
    const result = await performOperation(params);
    
    return {
      success: true,
      data: result
    };
  } catch (error) {
    // Log error for debugging
    console.error('Execution failed:', error);
    
    // Return user-friendly error
    return {
      success: false,
      error: {
        message: `Failed to process request: ${error.message}`,
        code: error.code || 'UNKNOWN_ERROR'
      }
    };
  }
}

Provide helpful error messages:

// ✅ Good: Specific, actionable error messages
if (!params.email) {
  throw new Error('Email parameter is required');
}
if (!isValidEmail(params.email)) {
  throw new Error('Invalid email format. Expected format: user@example.com');
}
 
// ❌ Bad: Vague, unhelpful error messages
if (!params.email || !isValidEmail(params.email)) {
  throw new Error('Error');
}

Handle edge cases explicitly:

function divide(numerator, denominator) {
  // Check for division by zero
  if (denominator === 0) {
    throw new Error('Cannot divide by zero');
  }
  
  // Check for non-finite numbers
  if (!Number.isFinite(numerator) || !Number.isFinite(denominator)) {
    throw new Error('Parameters must be finite numbers');
  }
  
  return numerator / denominator;
}

Testing

Test Thoroughly

Write unit tests for individual functions:

function testCalculateAverage() {
  // Test normal case
  assert(calculateAverage([1, 2, 3]) === 2);
  
  // Test single value
  assert(calculateAverage([5]) === 5);
  
  // Test negative numbers
  assert(calculateAverage([-1, 1]) === 0);
  
  // Test empty array
  assert(calculateAverage([]) === 0);
}

Write integration tests with realistic data:

async function testWeatherAPI() {
  const testCases = [
    { city: 'London', units: 'metric' },
    { city: 'New York', units: 'imperial' },
    { city: 'Tokyo', units: 'metric' }
  ];
  
  for (const testCase of testCases) {
    const result = await getWeather(testCase);
    assert(result.success === true);
    assert(typeof result.data.temperature === 'number');
    assert(result.data.city === testCase.city);
  }
}

Test edge cases and boundaries:

// Test empty inputs
await execute({ text: "" });
 
// Test single character
await execute({ text: "a" });
 
// Test very large inputs
await execute({ text: "word ".repeat(10000) });
 
// Test Unicode and special characters
await execute({ text: "Hello 世界 🌍" });
 
// Test invalid inputs
try {
  await execute({ text: null });
  assert(false, 'Should have thrown error');
} catch (error) {
  assert(error.message.includes('required'));
}