Retool OpenAPI Cache Demo

A test service designed to investigate and demonstrate OpenAPI specification caching behavior in Retool.

Background

When using Retool's OpenAPI resource integration with services that frequently update their API specifications, inconsistent behavior can occur if Retool is caching the OpenAPI spec. This project was created to provide a controlled environment for investigating such caching issues.

Problem Description

When deploying new versions of an API service with new operations added to the OpenAPI specification, Retool users may experience:

• Inconsistent results when calling newly added operations
• "Operation not found" errors mixed with successful calls
• Delays in Retool recognizing newly added endpoints

This behavior suggests that Retool may be caching the OpenAPI specification internally, rather than fetching the latest version each time an operation is called.

How This Service Works

This service provides a dynamic OpenAPI specification that changes in a predictable pattern over time:

• The service generates API endpoints based on a rolling 7-day (168-hour) window
• Each hour corresponds to exactly one endpoint
• As time passes, new endpoints are automatically added and old ones removed
• All endpoints are functional and will respond to requests
• The OpenAPI specification is updated in real-time

By observing how Retool interacts with this constantly changing API specification, you can confirm whether caching is occurring and understand its behavior patterns.

Key Features

• Rolling 7-day Window: Maintains exactly 168 hours (7 days) of operations at any time
• Anti-cache Headers: The OpenAPI endpoint includes proper headers to discourage caching
• Informative Dashboard: A web UI showing all available endpoints and metadata
• Full Functionality: All generated endpoints are actual working endpoints
• Detailed Logging: Server logs all spec requests and endpoint calls for debugging

How To Use This Tool

Public Hosted Service

A public instance of this service is available at:

https://dynamic-openapi.tylerstiene.ca

You can use this hosted instance directly in your Retool testing without deploying the service yourself.

Self-Deployment Steps (Optional)

If you prefer to deploy your own instance:

1. Deploy the Service:

   # Clone the repository
   git clone https://github.com/your-username/retool-openapi-cache-demo.git
   cd retool-openapi-cache-demo
   
   # Build and run
   go build -o dynamic-openapi-service
   ./dynamic-openapi-service

2. Configure in Retool:

   • In Retool, add a new OpenAPI resource
   • Set the "OpenAPI Spec URL" to https://dynamic-openapi.tylerstiene.ca/openapi.json (or your custom URL if self-hosted)
   • Configure authentication if needed
   • Test the connection

3. Create Test Components:

   • Create query components that call different endpoints from the specification
   • Include both older and newly added endpoints in your tests

Advanced Configuration

Environment Variables

• PORT: Set the server port (default: 8080)

Code Customization

The service has several constants that can be modified:

• ROLLING_WINDOW_DAYS: Change the number of days in the rolling window (default: 7)

Technical Details

Endpoint Format

Generated endpoints follow this pattern:

/api/operation_YYYYMMDD_HHMMSS

Example: /api/operation_20250330_120000

Service Endpoints

• /openapi.json: The OpenAPI specification
• /: Dashboard UI showing the current state of the service
• /api/operation_*: Dynamic endpoints that respond with JSON data

Response Format

All dynamic endpoints return a JSON response with:

{
  "status": "success",
  "message": "This is the operation_20250330_120000 endpoint",
  "timestamp": "2025-03-30T12:00:00Z",
  "endpoint_created_at": "2025-03-30T12:00:00Z",
  "valid_until": "2025-04-06T12:00:00Z"
}

License

MIT License

Contributing

Contributions to improve the service or documentation are welcome. Please feel free to submit pull requests or open issues.