Using PUT Method in hmm-api
Basic Usage
1. Import and Create API Client
import ApiClient from "hmm-api";
// Create an API client
const api = new ApiClient();
2. Simple PUT Request
// Replace entire user resource
const completeUserData = {
name: "John Doe",
email: "john@example.com",
age: 30,
active: true,
};
const response = await api.put("/users/123", completeUserData);
// Check if request was successful
if (response.success) {
console.log("User completely updated");
} else {
// Handle any errors
console.error(response.error);
}
Advanced Usage
With Type Safety
// Define interfaces for full resource replacement
interface UserResource {
id: number;
name: string;
email: string;
age: number;
active: boolean;
}
const fullUserUpdate: UserResource = {
id: 123,
name: "John Doe",
email: "john.doe@example.com",
age: 31,
active: true,
};
const response = await api.put<UserResource>("/users/123", fullUserUpdate);
if (response.success) {
// TypeScript knows the exact shape of the response
const updatedUser = response.data;
console.log(updatedUser.name);
}
Custom Options
Add Headers
const response = await api.put("/users/123", fullUserUpdate, {
headers: {
"X-Update-Reason": "Profile Revision",
Authorization: `Bearer ${yourAuthToken}`,
},
});
Control Error Toasts
// Disable error notifications for this request
const response = await api.put("/users/123", fullUserUpdate, {
showErrorToast: false,
});
Add a Cleanup Function
const response = await api.put("/users/123", fullUserUpdate, {
finally: () => {
// This runs after the request, whether it succeeds or fails
resetForm();
hideLoadingSpinner();
},
});
Full Example Scenario
import ApiClient from "hmm-api";
// Assuming you have a toast library configured
const api = new ApiClient({
toast: yourToastLibrary,
});
async function updateEntireUserProfile() {
// Complete profile replacement
const completeProfile = {
username: "johndoe",
email: "john.doe@example.com",
profile: {
firstName: "John",
lastName: "Doe",
bio: "Software developer",
skills: ["TypeScript", "React", "Node.js"],
},
settings: {
theme: "dark",
notifications: true,
},
};
const response = await api.put<UserProfile>("/profile", completeProfile, {
headers: {
Authorization: `Bearer ${yourAuthToken}`,
},
showErrorToast: true,
finally: () => {
clearFormState();
},
});
if (response.success) {
// Replace entire local profile
replaceEntireProfile(response.data);
showSuccessNotification("Profile completely updated");
}
}
Key Differences from PATCH
PUT vs PATCH
- PUT: Replaces the entire resource
- PATCH: Updates only specific fields
// PUT - Replaces entire resource
api.put("/users/123", {
// Must include ALL fields
name: "New Name",
email: "new@email.com",
age: 30,
// All previous fields must be included
});
// PATCH - Updates only specific fields
api.patch("/users/123", {
// Only update what's needed
name: "New Name",
});
Practical Considerations
Complete Resource Replacement
// Ensure you send ALL required fields
const completeResourceUpdate = {
// Include ALL fields expected by the server
id: 123,
name: "Updated Name",
email: "updated@example.com",
// All other fields must be present
createdAt: new Date().toISOString(),
};
const response = await api.put("/resources/123", completeResourceUpdate);
Quick Tips
- PUT completely replaces the existing resource
- Always include ALL required fields
- Be cautious about unintentionally removing data
- Leverage type safety for comprehensive updates
- Handle potential data loss carefully