Evolutics API SDK

A comprehensive Angular HTTP client SDK for making API requests with advanced features including caching, retry logic, file uploads, and flexible request configurations.

Features

• 🚀 Complete HTTP Methods: GET, POST, PUT, PATCH, DELETE with full TypeScript support
• 📁 File Upload Support: FormData handling for file uploads with endorsement headers
• 🔄 Retry Logic: Configurable retry attempts for failed requests
• 📊 Progress Reporting: Track upload/download progress
• 🎯 Flexible Request Types: Support for query parameters, request bodies, and text responses
• 🔐 Authentication: Built-in endorsement header support
• 📝 Comprehensive Logging: Optional route logging for debugging
• 🛠️ TypeScript: Full type safety and IntelliSense support

Installation

npm install @evolutics/api-sdk

Peer Dependencies

This SDK requires the following peer dependencies:

npm install @angular/common@^20.3.0 @angular/core@^20.3.0 @evolutics/ts@^0.1.0

Quick Start

1. Import and Initialize

import { ApiService } from '@evolutics/api-sdk';

@Component({
  // ... component config
})
export class MyComponent {
  constructor(private apiService: ApiService) {
    // Initialize with base URL and retry count
    this.apiService.init({
      baseURL: 'https://api.example.com',
      retryCount: 3
    });
  }
}

2. Basic Usage

// GET request
this.apiService.get<User[]>('/users')
  .subscribe(users => console.log(users));

// POST request with data
this.apiService.post<User>('/users', { name: 'John Doe', email: '[email protected]' })
  .subscribe(user => console.log('Created:', user));

// PUT request
this.apiService.put<User>('/users/1', { name: 'Jane Doe' })
  .subscribe(user => console.log('Updated:', user));

// DELETE request
this.apiService.delete('/users/1')
  .subscribe(() => console.log('User deleted'));

API Reference

ApiService

The main service class that provides all HTTP methods and utilities.

Methods

GET Requests

// Basic GET request
get<T>(route: string, parameters?: IObjectLiteral, extras?: IAPIRequestExtras): Observable<T>

// GET with text response
getText<T = string>(route: string, parameters?: { [field: string]: string | number | boolean }, extras?: IAPIRequestExtras): Observable<T>

// GET for file download
getFile<T = string>(route: string, parameters?: { [field: string]: string | number | boolean }, extras?: IAPIRequestExtras): Observable<T>

// GET with request body
getWithBody<T>(route: string, body?: any, extras?: IAPIRequestExtras): Observable<T>

POST Requests

// Basic POST request
post<T>(route: string, body?: any, extras?: IAPIRequestExtras): Observable<T>

// POST with FormData (file upload)
postFile<T>(route: string, body: FormData, extras?: IAPIRequestExtras): Observable<T>

// POST with FormData and endorsement
postFileWithEndorsement<T>(route: string, body: FormData): Observable<T>

// POST with string content
postString(route: string, body?: string, extras?: IAPIRequestExtras): Observable<string>

PUT Requests

// Basic PUT request
put<T>(route: string, body?: IObjectLiteral | FormData, extras?: IAPIRequestExtras): Observable<T>

// PUT with FormData
putFile<T>(route: string, body: FormData, extras?: any): Observable<T>

// PUT with FormData and endorsement
putFileWithEndorsement<T>(route: string, body: FormData): Observable<T>

PATCH Requests

// PATCH request
patch<T>(route: string, body?: IObjectLiteral, extras?: IAPIRequestExtras): Observable<T>

DELETE Requests

// Basic DELETE request
delete<T>(route: string, extras?: IAPIRequestExtras): Observable<T>

// DELETE with request body
deleteWithBody<T>(route: string, body?: any, extras?: IAPIRequestExtras): Observable<T>

// DELETE with text response
deleteText(route: string, extras?: IAPIRequestExtras): Observable<string>

Utility Methods

// Initialize the service
init(config: { baseURL?: string; retryCount?: number }): void

// Convert object to FormData
objectToFormData(obj: IObjectLiteral): FormData

IAPIRequestExtras Interface

Configuration options for customizing HTTP requests:

interface IAPIRequestExtras {
  useEndorsement?: boolean;           // Add endorsement header
  reportProgress?: boolean;           // Enable progress reporting
  requestType?: 'queryParams';        // Send body as query parameters
  refreshCache?: boolean;             // Refresh cache after request
  isReturningText?: boolean;          // Expect text response instead of JSON
  options?: {                         // Additional Angular HttpClient options
    headers?: HttpHeaders;
    [x: string]: any;
  };
}

Usage Examples

Basic CRUD Operations

export class UserService {
  constructor(private apiService: ApiService) {}

  // Get all users
  getUsers(): Observable<User[]> {
    return this.apiService.get<User[]>('/users');
  }

  // Get user by ID
  getUser(id: number): Observable<User> {
    return this.apiService.get<User>(`/users/${id}`);
  }

  // Create user
  createUser(user: CreateUserDto): Observable<User> {
    return this.apiService.post<User>('/users', user);
  }

  // Update user
  updateUser(id: number, user: UpdateUserDto): Observable<User> {
    return this.apiService.put<User>(`/users/${id}`, user);
  }

  // Delete user
  deleteUser(id: number): Observable<void> {
    return this.apiService.delete(`/users/${id}`);
  }
}

File Upload

// Upload single file
uploadFile(file: File): Observable<UploadResponse> {
  const formData = new FormData();
  formData.append('file', file);
  
  return this.apiService.postFile<UploadResponse>('/upload', formData);
}

// Upload with endorsement header
uploadFileWithAuth(file: File): Observable<UploadResponse> {
  const formData = new FormData();
  formData.append('file', file);
  
  return this.apiService.postFileWithEndorsement<UploadResponse>('/upload', formData);
}

// Convert object to FormData
uploadUserData(userData: any, file: File): Observable<Response> {
  const formData = this.apiService.objectToFormData({
    ...userData,
    file: file
  });
  
  return this.apiService.postFile<Response>('/users/upload', formData);
}

Advanced Request Configuration

// Request with custom headers
getDataWithCustomHeaders(): Observable<Data> {
  return this.apiService.get<Data>('/data', null, {
    options: {
      headers: new HttpHeaders({
        'X-API-Key': 'your-api-key',
        'X-Custom-Header': 'custom-value'
      })
    }
  });
}

// Request with endorsement and text response
getTextData(): Observable<string> {
  return this.apiService.get<string>('/text-data', null, {
    useEndorsement: true,
    isReturningText: true
  });
}

// PUT request with query parameters
updateStatus(id: number, status: string): Observable<Response> {
  return this.apiService.put<Response>(`/users/${id}/status`, { status }, {
    requestType: 'queryParams'
  });
}

// Request with progress reporting
uploadWithProgress(file: File): Observable<UploadResponse> {
  const formData = new FormData();
  formData.append('file', file);
  
  return this.apiService.postFile<UploadResponse>('/upload', formData, {
    reportProgress: true
  });
}

Error Handling

this.apiService.get<User[]>('/users')
  .subscribe({
    next: (users) => console.log('Users loaded:', users),
    error: (error) => console.error('Error loading users:', error)
  });

Configuration

Service Initialization

// Initialize with base URL only
this.apiService.init({ baseURL: 'https://api.example.com' });

// Initialize with retry count
this.apiService.init({ retryCount: 3 });

// Initialize with both
this.apiService.init({ 
  baseURL: 'https://api.example.com',
  retryCount: 2
});

Global Configuration

You can also set the base URL directly:

this.apiService.baseURL = 'https://api.example.com';

Development

Building the Library

ng build sdk

Running Tests

ng test

Generating Documentation

npm run docs

Publishing

# Build and publish to npm
npm run publish:npm

# Or use version-specific release commands
npm run release:patch  # 1.1.0 -> 1.1.1
npm run release:minor  # 1.1.0 -> 1.2.0
npm run release:major  # 1.1.0 -> 2.0.0

License

This project is licensed under the MIT License.

Support

For support and questions, please contact the Evolutics team or create an issue in the repository.