Quick Start

TypeScript
// Basic GET controller
export const getUsersController = async (
  qsParams: User.UserQueryStringParams,
): Promise<AxiosResponse<App.Pagination<User.User>, any>> => {
  const url = `/api/users/`;
  const instance = genRequestInstance();
  
  try {
    const response = await instance.get(url, { params: qsParams });
    return response;
  } catch (error) {
    console.error('Erro na requisição:', error);
    return Promise.reject(error);
  }
};

Workflow

When you need a new GET controller:

Progress:

• Define function name (entity + Controller suffix)
• Identify URL parameters (0 or more path segments)
• Define query string parameter types
• Define response data types
• Generate controller with proper error handling

Step 1: Analyze the endpoint structure

• Count URL parameters needed
• Identify the base endpoint path

Step 2: Collect type definitions Ask user: "What should be the TypeScript interface for query string parameters?" Ask user: "What should be the TypeScript interface for the response data?"

Step 3: Generate controller function

• Use descriptive function name ending in "Controller"
• Include all URL parameters as function parameters
• Add query string parameters
• Use consistent error handling pattern

Examples

Example 1: No URL parameters Input: Endpoint /api/users/, QueryParams: UserQueryStringParams, Response: User.User[] Output:

TypeScript
export const getUsersController = async (
  qsParams: UserQueryStringParams,
): Promise<AxiosResponse<User.User[], any>> => {
  const url = `/api/users/`;
  const instance = genRequestInstance();
  
  try {
    const response = await instance.get(url, { params: qsParams });
    return response;
  } catch (error) {
    console.error('Erro na requisição:', error);
    return Promise.reject(error);
  }
};

Example 2: Single URL parameter Input: Endpoint /api/users/{userId}/posts/, QueryParams: PostQueryStringParams, Response: Post.Post[] Output:

TypeScript
export const getUserPostsController = async (
  userId: User.User['id'],
  qsParams: PostQueryStringParams,
): Promise<AxiosResponse<Post.Post[], any>> => {
  const url = `/api/users/${userId}/posts/`;
  const instance = genRequestInstance();
  
  try {
    const response = await instance.get(url, { params: qsParams });
    return response;
  } catch (error) {
    console.error('Erro na requisição:', error);
    return Promise.reject(error);
  }
};

Example 3: Multiple URL parameters Input: Endpoint /api/projects/{projectId}/versions/{versionId}/tasks/ Output:

TypeScript
export const getProjectVersionTasksController = async (
  projectId: Project.Project['id'],
  versionId: Version.Version['id'],
  qsParams: TaskQueryStringParams,
): Promise<AxiosResponse<Task.Task[], any>> => {
  const url = `/api/projects/${projectId}/versions/${versionId}/tasks/`;
  const instance = genRequestInstance();
  
  try {
    const response = await instance.get(url, { params: qsParams });
    return response;
  } catch (error) {
    console.error('Erro na requisição:', error);
    return Promise.reject(error);
  }
};

Best Practices

• Naming Convention: Use descriptive names ending with "Controller"
• Parameter Order: URL parameters first, then query string parameters
• Type Safety: Use proper TypeScript interfaces for all parameters and responses
• Error Handling: Always include try-catch with console.error and Promise.reject
• URL Construction: Use template literals for clean URL building
• Consistent Structure: Follow the established pattern for maintainability

Common Pitfalls

• Don't mix parameter order - URL params always come before query string params
• Don't forget the trailing slash in URL paths if the API expects it
• Don't use generic types like any for query params or response data
• Don't handle errors differently - stick to the console.error + Promise.reject pattern
• Don't forget to export the function
• Don't use unclear function names - be explicit about what entity/resource is being fetched