NAM-APJATEL-BACKEND/BULK_IMAGES_QUICK_REF.md

Device Bulk Operations with Images - Quick Reference

Endpoints Summary

Operation	Endpoint	Method	Content-Type
Bulk Create (no images)	/device/bulk/create	POST	application/json
Bulk Create (with images)	/device/bulk/create	POST	multipart/form-data
Bulk Update (no images)	/device/bulk/update	PUT	application/json
Bulk Update (with images)	/device/bulk/update	PUT	multipart/form-data
Bulk Delete	/device/bulk/delete	DELETE	application/json

---

Quick Examples

Create with Images (cURL)

curl -X POST http://localhost:8080/device/bulk/create \
  -H "Authorization: Bearer TOKEN" \
  -F 'devices=[{"device_code":"ODP-001","device_type":"ODP","longitude":106.8,"latitude":-6.2,"port_amount":8,"status":"active"}]' \
  -F 'image_indexes=[2]' \
  -F "images=@photo1.jpg" \
  -F "images=@photo2.jpg"

Create with Images (JavaScript)

const formData = new FormData();
formData.append('devices', JSON.stringify([
  {
    device_code: "ODP-001",
    device_type: "ODP",
    longitude: 106.8,
    latitude: -6.2,
    port_amount: 8,
    status: "active"
  }
]));
formData.append('image_indexes', JSON.stringify([2])); // 2 images for device
formData.append('images', file1);
formData.append('images', file2);

fetch('/device/bulk/create', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer TOKEN' },
  body: formData
});

Update with Images (JavaScript)

const formData = new FormData();
formData.append('device_ids', JSON.stringify([
  "550e8400-e29b-41d4-a716-446655440000"
]));
formData.append('updates', JSON.stringify({ status: "maintenance" }));
formData.append('image_indexes', JSON.stringify([3])); // Add 3 new images
formData.append('replace_images', 'false'); // Append to existing
formData.append('images', file1);
formData.append('images', file2);
formData.append('images', file3);

fetch('/device/bulk/update', {
  method: 'PUT',
  headers: { 'Authorization': 'Bearer TOKEN' },
  body: formData
});

---

Form Fields (Multipart)

Bulk Create with Images

Field	Type	Required	Description
devices	JSON string	✅	Array of device objects
image_indexes	JSON array	✅	Number of images per device
images	Files	✅	Image files in order

Bulk Update with Images

Field	Type	Required	Description
device_ids	JSON array	✅	Array of UUIDs
updates	JSON object	✅	Fields to update
image_indexes	JSON array	✅	Number of images per device
replace_images	String	❌	"true" or "false" (default: false)
images	Files	✅	Image files in order

---

Image Distribution Rules

// Example: 3 devices with different image counts
devices = [device1, device2, device3]
image_indexes = [2, 0, 1]  // device1: 2 imgs, device2: 0 imgs, device3: 1 img
images = [img1, img2, img3] // Total: 3 images (2+0+1)

// Result:
// device1 → [img1, img2]
// device2 → []
// device3 → [img3]

Rules:

• ✅ len(image_indexes) == len(devices) or len(device_ids)
• ✅ sum(image_indexes) == len(images)
• ✅ Images assigned in sequential order

---

Response Format

{
  "message": "Bulk create completed: 2 successful, 0 failed out of 2 requested (with 3 images)",
  "data": {
    "total_requested": 2,
    "successful": 2,
    "failed": 0,
    "errors": [],
    "results": [
      {
        "id": "uuid-here",
        "device_code": "ODP-001",
        "image_url": "/uploads/devices/primary.jpg",
        "image_urls": [
          "/uploads/devices/primary.jpg",
          "/uploads/devices/secondary.jpg"
        ]
      }
    ],
    "execution_time": "150ms"
  }
}

---

Validation

Device

• ✅ Type: "ODP", "OTB", or "closure"
• ✅ Status: "active", "inactive", or "maintenance"
• ✅ Port amount > 0 for ODP/OTB
• ✅ OLT only for ODP devices

Images

• ✅ Max size: 5MB per file
• ✅ Formats: .jpg, .jpeg, .png, .webp
• ✅ Max request: 100MB total

---

Common Errors

Error	Cause	Solution
image_indexes length (3) must match devices length (2)	Mismatch in array lengths	Ensure len(image_indexes) == len(devices)
total images (5) doesn't match sum (4)	Wrong image count	Ensure sum(image_indexes) == len(images)
file size exceeds 5MB limit	Image too large	Compress image or reduce quality
Invalid device type	Wrong type value	Use "ODP", "OTB", or "closure"
Only ODP devices can be assigned to OLT	OLT on wrong type	Only set olt_id for ODP devices

---

Performance Tips

✅ Keep batches under 50 devices
✅ Compress images before upload
✅ Use JSON mode when no images needed
✅ Check errors array for partial failures
✅ 4-10x faster than individual requests

---

Testing with Postman

1. Method: POST or PUT
2. URL: http://localhost:8080/device/bulk/create
3. Headers:
   • Authorization: Bearer YOUR_TOKEN
4. Body: form-data
   • devices (Text): [{...}]
   • image_indexes (Text): [2,1]
   • images (File): Select files
   • images (File): Select files
   • images (File): Select files

---

Authorization

Required Roles: Teknisi, Admin, Super Admin
Header: Authorization: Bearer JWT_TOKEN

---

See Full Documentation

📖 DEVICE_BULK_IMAGES_GUIDE.md - Complete guide with all details