DELETE Method

How to make DELETE requests with speedcast-api

🗑️ Using DELETE Method

DELETE requests are used to remove resources from the server. Always use with caution as these operations are often irreversible.

Basic Usage

1. Import and Create API Client

import { SpeedcastApi } from 'speedcast-api';

// Create an API client
const api = new SpeedcastApi({
  baseURL: 'https://api.example.com'
});

2. Simple DELETE Request

// Delete a user by ID
const response = await api.delete('/users/123');

// Process the response directly
console.log(`Status: ${response.status}`); // e.g., 204 No Content
console.log('User deleted successfully');

Advanced Usage

With Type Safety

// Define a response interface if the API returns specific data
interface DeleteResponse {
  message: string;
  deletedId: number;
}

const response = await api.delete<DeleteResponse>('/users/123');

// TypeScript knows the exact shape of the response
const deleteResult = response.data;
console.log(deleteResult.message);

Adding Custom Options

Add Headers

const response = await api.delete('/users/123', {
  headers: {
    'X-Reason': 'Account Closure',
    'Authorization': `Bearer ${yourAuthToken}`,
  },
});

Set Timeout

const response = await api.delete('/users/123', {
  timeout: 8000, // 8 seconds
});

Configure Retries

const response = await api.delete('/users/123', {
  retries: 2, // Retry twice if it fails
});

Error Handling

try {
  const response = await api.delete('/users/123');
  console.log('Deletion successful');
} catch (error) {
  console.error('Deletion failed:', error);
}

Full Example Scenario

import { SpeedcastApi } from 'speedcast-api';

const api = new SpeedcastApi({
  baseURL: 'https://api.example.com',
  defaultHeaders: {
    'Accept': 'application/json',
    'User-Agent': 'MyAwesomeApp/1.0'
  }
});

async function removeUser(userId: number) {
  try {
    const response = await api.delete<{ message: string }>(`/users/${userId}`, {
      headers: {
        'Authorization': `Bearer ${yourAuthToken}`,
        'X-Reason-Code': 'USER_REQUESTED'
      },
      timeout: 10000, // 10 seconds
      retries: 1      // Retry once if it fails
    });
    
    // User successfully deleted
    console.log('User removed:', response.data.message);
    removeUserFromLocalState(userId);
    return true;
  } catch (error) {
    // Handle deletion failure
    console.error('Failed to delete user:', error);
    return false;
  }
}

Practical Considerations

Deleting with Query Parameters

// Delete with additional parameters using URL
const response = await api.delete('/items?status=inactive&olderThan=30days');

// Or using full URL
const response = await api.delete('https://api.example.com/items?status=inactive');

Response Structure

The response from a DELETE request has the following structure:

interface ApiResponse<T = any> {
  data: T;                           // Response data (if any)
  status: number;                    // HTTP status code
  statusText: string;                // HTTP status text
  headers: Record<string, string>;   // Response headers
}

💡 Quick Tips

  • Common success status codes for DELETE: 204 (No Content) or 200 (OK)
  • Use try/catch blocks to handle potential errors
  • Consider implementing a confirmation step before making DELETE requests
  • Use type parameters for type-safe responses if your API returns data
  • Many DELETE endpoints don't return response bodies (204 No Content)