Plant Information API

A REST API that provides detailed plant information using OpenAI's GPT model with intelligent caching for improved performance and reduced API costs.

├── index.ts                 # Main HTTP entry point (Hono app)
├── backend/
│   └── database/
│       └── cache.ts         # Database cache functions
├── test.html               # Plant API testing interface
├── admin.html              # Cache admin interface
└── README.md

• Get comprehensive plant information by name
• Structured JSON response with 8 key plant characteristics
• Powered by OpenAI GPT-4o-mini for accurate plant data
• Intelligent caching system - stores successful responses and serves cached data for repeated requests
• Admin authentication - secure login system to protect cache management and admin features
• Cache management endpoints for monitoring and administration
• Automatic plant name normalization for consistent caching

Simple testing interface for the Plant API with comprehensive features:

• Interactive plant lookup: Enter plant names and see real-time API responses
• API documentation: Built-in instructions showing all available endpoints and usage examples
• Request URL display: Shows the exact URL used for each request with copy-to-clipboard functionality
• Response formatting: Pretty-printed JSON responses with syntax highlighting
• Error handling: Clear display of API errors and network issues
• Admin panel access: Direct link to cache management interface
• Caching indicators: Visual feedback showing whether responses came from cache or fresh API calls

Returns API information, usage instructions, and cache statistics.

Authentication Required - Simple admin interface for viewing the cache database. Displays:

• Total number of cached entries
• List of all cached plants with their full JSON data
• Plant names, IDs, and creation timestamps
• Cache management controls (refresh, clear cache)
• Logout functionality

Admin login page with username/password authentication. Required to access admin features and cache management endpoints.

Logs out the current admin session and redirects to the main page.

Returns detailed information about a specific plant. If the plant information is already cached, returns the cached response immediately. Otherwise, fetches new information from OpenAI and caches it for future requests.

Parameters:

• name (string, required): The name of the plant to look up

Response Format:

{
  "name": "Common and scientific name",
  "description": "Detailed description of the plant",
  "lightNeeds": "Light requirements",
  "soilNeeds": "Soil type and pH requirements", 
  "moistureNeeds": "Watering requirements",
  "bloomTime": "Blooming season/months",
  "height": "Mature height range",
  "spread": "Mature spread/width range",
  "_cached": true,
  "_cacheTimestamp": "2024-01-01T12:00:00.000Z"
}

Cache Indicators:

• _cached: Boolean indicating if the response came from cache (true) or OpenAI (false)
• _cacheTimestamp: ISO timestamp of when the response was generated

Example Request:

GET /plant/rose

Example Response (from cache):

{
  "name": "Rose (Rosa spp.)",
  "description": "Roses are woody perennial flowering plants with fragrant blooms...",
  "lightNeeds": "Full sun (6+ hours direct sunlight daily)",
  "soilNeeds": "Well-draining, fertile soil with pH 6.0-7.0",
  "moistureNeeds": "Regular watering, 1-2 inches per week",
  "bloomTime": "Late spring through fall (May-October)",
  "height": "1-8 feet depending on variety",
  "spread": "2-6 feet depending on variety",
  "_cached": true,
  "_cacheTimestamp": "2024-01-01T12:00:00.000Z"
}

Health check endpoint that returns API status.

Authentication Required - Returns cache statistics including total cached entries and timestamps.

Response Format:

{
  "totalEntries": 15,
  "oldestEntry": "2024-01-01T10:00:00.000Z",
  "newestEntry": "2024-01-01T12:00:00.000Z"
}

Authentication Required - Returns a list of all cached plants with their normalized names and creation timestamps.

Response Format:

{
  "totalEntries": 2,
  "plants": [
    {
      "plantName": "Rose",
      "normalizedName": "rose",
      "createdAt": "2024-01-01T12:00:00.000Z"
    },
    {
      "plantName": "Japanese Maple",
      "normalizedName": "japanese_maple",
      "createdAt": "2024-01-01T11:30:00.000Z"
    }
  ]
}

Authentication Required - Clears all cached plant information. Useful for maintenance or testing.

Response Format:

{
  "message": "Cache cleared successfully",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Authentication Required - Admin endpoint that returns complete cache data including full plant information for each entry. Used by the admin interface.

Response Format:

{
  "totalEntries": 2,
  "entries": [
    {
      "id": 1,
      "plantName": "Rose",
      "normalizedName": "rose",
      "plantInfo": {
        "name": "Rose (Rosa spp.)",
        "description": "Roses are woody perennial flowering plants...",
        "lightNeeds": "Full sun (6+ hours direct sunlight daily)",
        "soilNeeds": "Well-draining, fertile soil with pH 6.0-7.0",
        "moistureNeeds": "Regular watering, 1-2 inches per week",
        "bloomTime": "Late spring through fall (May-October)",
        "height": "1-8 feet depending on variety",
        "spread": "2-6 feet depending on variety"
      },
      "createdAt": "2024-01-01T12:00:00.000Z",
      "updatedAt": "2024-01-01T12:00:00.000Z"
    }
  ]
}

The API includes a secure authentication system to protect admin features and cache management endpoints.

Configure authentication by setting these environment variables:

• ADMIN_USERNAME - Admin username (defaults to 'admin')
• ADMIN_PASSWORD - Admin password (defaults to 'password123')
• SESSION_SECRET - Secret key for session management (defaults to 'your-secret-key-change-this')

Important: Change the default credentials before deploying to production!

The following endpoints require admin authentication:

• /admin - Admin interface
• /admin/cache/full - Full cache data API
• /cache/stats - Cache statistics
• /cache/list - List cached plants
• /cache/clear - Clear cache (POST)

• Sessions are managed using secure HTTP-only cookies
• Sessions expire after 24 hours
• Use /login to authenticate and /logout to end sessions
• Unauthenticated requests to protected endpoints return 401 status or redirect to login

The API returns appropriate HTTP status codes:

• 200: Success
• 400: Bad request (missing plant name)
• 401: Unauthorized (authentication required)
• 500: Server error (OpenAI API issues, parsing errors)

Error responses include descriptive error messages and may include additional debugging information.

# Access the testing interface (web browser)
# Visit: https://your-api-url/

# Get API information and statistics
curl https://your-api-url/api

# Get information about a rose (will cache the response)
curl https://your-api-url/plant/rose

# Get information about the same rose again (will return cached response)
curl https://your-api-url/plant/rose

# Get information about a tomato plant
curl https://your-api-url/plant/tomato

# Get information about a Japanese maple (spaces are handled automatically)
curl https://your-api-url/plant/japanese%20maple

# Check cache statistics (requires authentication)
curl -b cookies.txt https://your-api-url/cache/stats

# List all cached plants (requires authentication)
curl -b cookies.txt https://your-api-url/cache/list

# Clear the cache (requires authentication)
curl -X POST -b cookies.txt https://your-api-url/cache/clear

# Access the admin interface (web browser, requires login)
# Visit: https://your-api-url/admin

# Login page (web browser)
# Visit: https://your-api-url/login

• Plant name normalization: Plant names are normalized (lowercased, special characters removed, spaces converted to underscores) for consistent caching
• Cache hits: Subsequent requests for the same plant (even with different capitalization or spacing) will return cached responses instantly
• Cache misses: New plants trigger OpenAI API calls and the responses are automatically cached
• Performance: Cached responses are served in milliseconds vs. seconds for OpenAI API calls
• Cost efficiency: Reduces OpenAI API usage and associated costs

• Main entry point: index.ts at project root with HTTP trigger
• Built with Hono framework
• Uses OpenAI GPT-4o-mini model
• SQLite database for caching with automatic table creation
• Secure authentication system with session management and HTTP-only cookies
• Includes input validation and error handling
• Returns structured JSON responses
• Supports URL-encoded plant names
• Intelligent plant name normalization for cache consistency
• Cache management endpoints for monitoring and administration
• Protected admin interface with login/logout functionality