Skip to main content

​
GET /api/folders

Returns the folder structure and contents for slideshow navigation and admin management.

​
Parameters

​
path
string
Specific folder path to get contents from. If not provided, returns root level structure.

​
Request Examples

Root Structure
curl http://localhost:3000/api/folders
Specific Folder
curl "http://localhost:3000/api/folders?path=vacation/2023"

​
Response

{
  "success": true,
  "data": {
    "currentPath": "",
    "folders": [
      {
        "name": "vacation",
        "path": "vacation",
        "imageCount": 45,
        "subfolderCount": 3,
        "lastModified": "2023-07-20T15:30:00Z"
      },
      {
        "name": "family-photos",
        "path": "family-photos", 
        "imageCount": 128,
        "subfolderCount": 5,
        "lastModified": "2023-06-15T09:20:00Z"
      }
    ],
    "images": [
      {
        "name": "welcome.jpg",
        "path": "welcome.jpg",
        "size": 2048576,
        "lastModified": "2023-05-01T12:00:00Z",
        "dimensions": {
          "width": 1920,
          "height": 1080
        }
      }
    ],
    "totalFolders": 2,
    "totalImages": 1
  }
}

{
  "success": true,
  "data": {
    "currentPath": "vacation/2023",
    "parentPath": "vacation",
    "folders": [
      {
        "name": "summer",
        "path": "vacation/2023/summer",
        "imageCount": 23,
        "subfolderCount": 0,
        "lastModified": "2023-07-15T14:20:00Z"
      },
      {
        "name": "winter",
        "path": "vacation/2023/winter",
        "imageCount": 18,
        "subfolderCount": 0,
        "lastModified": "2023-02-28T10:45:00Z"
      }
    ],
    "images": [
      {
        "name": "beach-sunset.jpg",
        "path": "vacation/2023/beach-sunset.jpg",
        "size": 3145728,
        "lastModified": "2023-07-10T18:30:00Z",
        "dimensions": {
          "width": 2560,
          "height": 1440
        }
      }
    ],
    "totalFolders": 2,
    "totalImages": 1
  }
}

​
Response Fields

​
currentPath
string
Current folder path being viewed
​
parentPath
string
Path to parent folder (null for root level)
​
folders
array
Array of subfolders in current directory
​
images
array
Array of images in current directory
​
totalFolders
number
Count of subfolders in current directory
​
totalImages
number
Count of images in current directory

​
Folder Object

​
name
string
Folder display name
​
path
string
Full path to folder from root
​
imageCount
number
Number of images in this folder (recursive)
​
subfolderCount
number
Number of direct subfolders
​
lastModified
string
ISO timestamp of last modification

​
Image Object

​
name
string
Image filename
​
path
string
Full path to image from root
​
size
number
File size in bytes
​
dimensions
object
Image width and height in pixels
​
lastModified
string
ISO timestamp of last modification

​
Status Codes

​
200
Success
Folder contents retrieved successfully
​
404
Not Found
Specified folder path does not exist
​
500
Server Error
Error accessing file system

​
Usage Example

async function loadFolderContents(folderPath = '') {
  try {
    const url = folderPath 
      ? `/api/folders?path=${encodeURIComponent(folderPath)}`
      : '/api/folders';
      
    const response = await fetch(url);
    const data = await response.json();
    
    if (data.success) {
      return {
        folders: data.data.folders,
        images: data.data.images,
        currentPath: data.data.currentPath,
        parentPath: data.data.parentPath
      };
    } else {
      throw new Error(data.error);
    }
  } catch (error) {
    console.error('Failed to load folder:', error);
    throw error;
  }
}

// Build folder navigation
function buildFolderTree() {
  loadFolderContents()
    .then(data => {
      data.folders.forEach(folder => {
        console.log(`${folder.name}: ${folder.imageCount} images`);
      });
    })
    .catch(error => {
      console.error('Navigation failed:', error);
    });
}

​
Path Handling

  • Use forward slashes for folder separators
  • Paths are relative to the uploads directory
  • URL encode folder names with special characters
  • Empty path parameter returns root level
  • Invalid paths return 404 error