garage-webui/docs/api-alignment-tasks.md

Garage Web UI API Alignment Task List

Overview

This document outlines the tasks required to fully align the Garage Web UI implementation with the official Garage Admin API v2 specification. The current implementation uses REST-compliant HTTP methods but may differ from the official specification.

Current Status: 18/55+ official v2 endpoints implemented (33% coverage)
Goal: Achieve full compliance with official API specification while maintaining REST best practices

---

🔧 High Priority: HTTP Method Alignment

Task 1: Verify and Align Delete Operations

• Research Official Specification: Confirm the exact HTTP methods specified for delete operations in the official docs
• Update DeleteKey Implementation:
  • Current: DELETE /v2/DeleteKey?id={id}
  • Official (likely): POST /v2/DeleteKey/{id}
  • Decision needed: Keep REST-compliant DELETE or align with official POST
• Update DeleteBucket Implementation:
  • Current: DELETE /v2/DeleteBucket?id={id}
  • Official (likely): POST /v2/DeleteBucket/{id}
  • Decision needed: Keep REST-compliant DELETE or align with official POST
• Update Frontend Hooks: Modify src/pages/keys/hooks.ts and src/pages/buckets/manage/hooks.ts if changes are made
• Test Compatibility: Ensure changes work with actual Garage server instances

Task 2: Review Other HTTP Methods

• Verify UpdateBucket Method: Confirm if POST /v2/UpdateBucket is correct vs potential PUT
• Check Alias Operations: Verify PUT/DELETE methods for alias operations are officially correct
• Validate All POST Operations: Ensure all POST endpoints match official specification

---

📋 Medium Priority: Missing Official Endpoints

Task 3: Implement Additional Cluster Management

• Add GetClusterStatistics: GET /v2/GetClusterStatistics
  • Create hook in src/pages/cluster/hooks.ts
  • Add UI component for cluster statistics display
  • Integrate into cluster dashboard
• Add PreviewClusterLayoutChanges: POST /v2/PreviewClusterLayoutChanges
  • Implement preview functionality before applying changes
  • Add confirmation dialog with preview results
• Add GetClusterLayoutHistory: GET /v2/GetClusterLayoutHistory
  • Create layout history viewer component
  • Add navigation to view past layout versions

Task 4: Implement Enhanced Bucket Features

• Add CleanupIncompleteUploads: POST /v2/CleanupIncompleteUploads
  • Create cleanup functionality in bucket management
  • Add scheduled/manual cleanup options
• Add InspectObject: GET /v2/InspectObject
  • Integrate into object browser
  • Add object inspection modal/page
• Add Enhanced Bucket Operations:
  • POST /v2/AddBucketAlias (if different from current implementation)
  • POST /v2/RemoveBucketAlias (if different from current implementation)

Task 5: Implement Key Management Enhancements

• Add GetKeyInfo: GET /v2/GetKeyInfo
  • Create key details page
  • Show key capabilities, expiration, etc.
• Add UpdateKey: POST /v2/UpdateKey/{id}
  • Add key editing functionality
  • Allow updating permissions, expiration, name

---

🚀 Low Priority: Advanced Features

Task 6: Admin Token Management

• Add Token Listing: GET /v2/ListAdminTokens
• Add Token Details: GET /v2/GetAdminTokenInfo
• Add Current Token Info: GET /v2/GetCurrentAdminTokenInfo
• Add Token Creation: POST /v2/CreateAdminToken
• Add Token Updates: POST /v2/UpdateAdminToken/{id}
• Add Token Deletion: POST /v2/DeleteAdminToken/{id}
• Create Admin Token Management UI:
  • Token listing page
  • Token creation wizard
  • Token permissions management

Task 7: Node Management & Monitoring

• Add Node Information: GET /v2/GetNodeInfo/{node}
• Add Node Statistics: GET /v2/GetNodeStatistics/{node}
• Add Metadata Snapshots: POST /v2/CreateMetadataSnapshot/{node}
• Add Repair Operations: POST /v2/LaunchRepairOperation/{node}
• Create Node Management UI:
  • Node dashboard with detailed information
  • Repair operation scheduler
  • Node health monitoring

Task 8: Worker Process Management

• Add Worker Listing: POST /v2/ListWorkers/{node}
• Add Worker Information: POST /v2/GetWorkerInfo/{node}
• Add Worker Variables: POST /v2/GetWorkerVariable/{node}
• Add Variable Setting: POST /v2/SetWorkerVariable/{node}
• Create Worker Management UI:
  • Worker process monitor
  • Variable configuration interface

Task 9: Block Management

• Add Block Information: POST /v2/GetBlockInfo/{node}
• Add Block Error Listing: GET /v2/ListBlockErrors/{node}
• Add Block Resync: POST /v2/RetryBlockResync/{node}
• Add Block Purging: POST /v2/PurgeBlocks/{node}
• Create Block Management UI:
  • Block health dashboard
  • Error resolution tools
  • Maintenance operations interface

---

🧪 Testing & Validation Tasks

Task 10: Compatibility Testing

• Test Against Multiple Garage Versions:
  • Test with Garage v2.0.x
  • Test with latest Garage version
  • Verify backward compatibility
• API Method Validation:
  • Test all current endpoints with official methods
  • Verify error handling consistency
  • Check response format compliance
• Integration Testing:
  • Test with real Garage clusters
  • Validate cluster operations end-to-end
  • Test authentication and authorization

Task 11: Error Handling Alignment

• Review Error Response Formats: Ensure they match official specification
• Update Error Messages: Align with official API error codes and messages
• Implement Proper Status Codes: Verify all HTTP status codes match specification

---

📚 Documentation & Maintenance Tasks

Task 12: Documentation Updates

• Update API Documentation: Align all endpoint documentation with official specification
• Add Implementation Notes: Document any intentional deviations from official spec
• Create Migration Guide: Document changes needed for users upgrading
• Update README: Reflect full API v2 compliance status

Task 13: Code Quality Improvements

• Type Definition Updates: Create proper TypeScript interfaces for all API responses
• Error Handling Standardization: Implement consistent error handling across all endpoints
• Code Documentation: Add comprehensive JSDoc comments to all API functions
• Unit Testing: Add tests for all API integration functions

---

🎯 Implementation Strategy

Phase 1: Core Alignment (Week 1-2)

1. Complete Tasks 1-2 (HTTP Method Alignment)
2. Implement Task 10 (Compatibility Testing)
3. Update documentation for changes

Phase 2: Essential Features (Week 3-4)

1. Complete Task 3 (Additional Cluster Management)
2. Complete Task 4 (Enhanced Bucket Features)
3. Complete Task 5 (Key Management Enhancements)

Phase 3: Advanced Features (Month 2)

1. Implement Tasks 6-9 based on user demand and priority
2. Complete comprehensive testing
3. Full documentation update

Phase 4: Maintenance (Ongoing)

1. Monitor official API updates
2. Maintain compatibility with new Garage versions
3. Address user feedback and issues

---

✅ Completion Criteria

• All official v2 endpoints implemented (100% coverage)
• HTTP methods align with official specification (or documented deviations)
• Comprehensive test coverage for all endpoints
• Updated documentation reflecting full compliance
• Successful testing against multiple Garage versions
• User feedback incorporated and addressed

---

Last Updated: July 2025
Next Review: Monthly or when official API specification changes