unleash-api-integration

Unleash API Integration Guidelines

When implementing new Unleash API integrations, follow these consistent patterns to maintain code quality and readability:

File Structure

• Place all Unleash API integrations in the src/unleash/ directory
• Use kebab-case for filenames (e.g., get-all-projects.ts, update-feature-toggle.ts)
• Name files according to their primary function

Implementation Pattern

1. Import the Unleash client:

import { client } from "./unleash-client.js";

1. Create and export an async function with descriptive name:

export async function functionName(parameters): Promise<ReturnType | null> {
  try {
    const response = await client.METHOD('/api/admin/endpoint');
    return response.data.specificProperty || response.data;
  } catch (error) {
    console.error('Error message:', error);
    return null;
  }
}

1. Use proper JSDoc comments:

/**
 * Brief description of what this function does
 * @param paramName Description of parameter
 * @returns Description of return value or null if unavailable
 */

1. When making requests:

   • Use HTTP methods (get, post, put, delete) directly from the client
   • Follow Unleash API endpoints from documentation at https://docs.getunleash.io/reference/api/unleash/unleash-api
   • Handle response data properly, accounting for possible response structures
   • Implement proper error handling with descriptive error messages

2. For POST/PUT requests, follow this pattern:

const response = await client.post('/api/admin/endpoint', {
  property1: value1,
  property2: value2
});

1. Use proper TypeScript types:
   • Define interfaces for request/response data
   • Use specific return types rather than any when possible
   • Consider using Zod for runtime validation when necessary

Testing

• Write unit tests for each API integration
• Mock the Axios client responses in tests
• Test both success and error scenarios

Error Handling

• Always wrap API calls in try/catch blocks
• Log informative error messages
• Return null on error to allow graceful degradation