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.

• 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
• Cache management endpoints for monitoring and administration
• Automatic plant name normalization for consistent caching

Returns API information, usage instructions, and cache statistics.

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.

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"
}

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"
    }
  ]
}

Clears all cached plant information. Useful for maintenance or testing.

Response Format:

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

The API returns appropriate HTTP status codes:

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

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

# 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
curl https://your-api-url/cache/stats

# List all cached plants
curl https://your-api-url/cache/list

# Clear the cache
curl -X POST https://your-api-url/cache/clear

• 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

• Built with Hono framework
• Uses OpenAI GPT-4o-mini model
• SQLite database for caching with automatic table creation
• 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