REST File Management API

This REST API allows clients to upload, read (download), update (replace), delete, and administer files on a server. Each file has four unique endpoints (URLs) generated at upload time, corresponding to the different operations.

Check this link to test the API with a user client: https://file.leosdisciple.com/manager/

Overview

1. Upload a File
   
   • Endpoint: POST /upload.php
   • Description: Allows a client to upload a file (typically via multipart/form-data).
   • Result: Server saves the file and returns a JSON response containing four unique links:
     • read_url
     • update_url
     • delete_url
     • admin_url
2. Read (Download) a File
   
   • Endpoint: GET /read.php?id=READ_ID
   • Description: Retrieves or downloads the uploaded file using the read_id.
   • Result: Returns the raw file content. Depending on the server’s configuration, the file may be displayed inline (if it’s an image or other supported type) or prompted for download.
3. Update (Replace) a File
   
   • Endpoint: POST /update.php?id=UPDATE_ID
   • Description: Replaces the previously uploaded file with a new file.
   • Result: The old file is removed from the server, and the new file is saved in its place.
4. Delete a File
   
   • Endpoint: DELETE /delete.php?id=DELETE_ID
   • Description: Removes the file from the server and deletes its database record.
   • Result: The file no longer exists on the server, and the links associated with it become invalid.
5. Admin (Retrieve Links)
   
   • Endpoint: GET /admin.php?id=ADMIN_ID
   • Description: Returns JSON with the four links related to the file (read, update, delete, and admin).
   • Result: Allows someone with the admin_id to recover or rediscover the file’s four unique endpoints.

Usage Details

1. Upload Process
   • Method: POST
   • Request Body: multipart/form-data containing the file under a key named file.
   • Response:

     {
       "success": true,
       "read_url": "https://file.leosdisciple.com/api/read.php?id=...",
       "update_url": "https://file.leosdisciple.com/api/update.php?id=...",
       "delete_url": "https://file.leosdisciple.com/api/delete.php?id=...",
       "admin_url":  "https://file.leosdisciple.com/api/admin.php?id=..."
     }

   • Usage: Store these returned URLs. They are required for subsequent file management.
2. Reading a File
   • Method: GET
   • URL: https://file.leosdisciple.com/api/read.php?id=READ_ID
   • Response: The raw file data. The exact behavior (inline vs. download) depends on the server’s MIME handling.
3. Updating a File
   • Method: POST
   • URL: https://file.leosdisciple.com/api/update.php?id=UPDATE_ID
   • Request Body: multipart/form-data containing the new file.
   • Response:

     {
       "success": true,
       "message": "File updated successfully."
     }

4. Deleting a File
   • Method: DELETE
   • URL: https://file.leosdisciple.com/api/delete.php?id=DELETE_ID
   • Response:

     {
       "success": true,
       "message": "File deleted successfully."
     }

5. Admin / Retrieve Links
   • Method: GET
   • URL: https://file.leosdisciple.com/api/admin.php?id=ADMIN_ID
   • Response:

     {
       "success": true,
       "read_url":   "https://file.leosdisciple.com/api/read.php?id=...",
       "update_url": "https://file.leosdisciple.com/api/update.php?id=...",
       "delete_url": "https://file.leosdisciple.com/api/delete.php?id=...",
       "admin_url":  "https://file.leosdisciple.com/api/admin.php?id=..."
     }

   • Usage: Useful for retrieving the four links if you only know the admin_id.

Technical Notes

• File Storage: By default, files are stored in a server-side directory (e.g., uploads/) with a unique name.
• Database: A table (e.g., files) stores the relationships between the generated IDs and the file path.
• Max File Size: The server can enforce a maximum upload size via both PHP.ini settings (post_max_size, upload_max_filesize) and custom checks in the code.
• Security:
  • Limit allowed file types or scan for viruses if necessary.
  • Only those with the correct ID can perform read, update, or delete. Protect or rotate these if you need stricter control.
• HTTP Methods: The REST approach uses POST for updates and DELETE for deletions.

Example Client Flows

1. Client Uploads a file, receives the JSON response with 4 links, and stores them.
2. To View/Download, the client calls GET read_url.
3. To Replace/Update, the client calls POST update_url with a new file.
4. To Delete, the client calls DELETE delete_url.
5. If the client only has the admin_id, it can retrieve the 4 links again by calling GET admin_url.

Summary

This API offers a straightforward mechanism to manage files via unique URLs for each operation. By separating file operations into distinct endpoints (read, update, delete, admin), the API ensures that each link is specialized and only reveals the intended functionality (e.g., read, update, or delete) to whoever possesses the correct URL/ID. This design is flexible for integrating into front-end applications, single-page apps, or even third-party services needing file hosting and management.