file-explorer-api-r2/README.md

Cloudflare Worker API Template

A production-ready template for building secure, modular APIs with Cloudflare Workers, featuring built-in authentication, database integration, and comprehensive documentation.

Features

• Authentication & Authorization: Pre-configured with API key and Bearer token authentication
• Database Integration: Ready-to-use D1 database connections
• Storage: R2 bucket integration for file storage
• Documentation: Auto-generated Swagger/OpenAPI documentation
• CI/CD: GitHub Actions workflows for automated deployments
• Environment Management: Development, Playtest, and Production environments

Design Documentation

All design documentation should be maintained in the blueprint repository:

1. Create design documentation in the blueprint repository located at <app_name_lower_case>
2. Submit the design as a Pull Request to the blueprint repository
3. Once approved, add the link to the design file in docs/DESIGN.md

The docs/DESIGN.md file should contain a reference to the design document's location in the blueprint repository.

Getting Started

Using This Template

1. Checkout the template branch:

   git clone <repository-url>
   git checkout template
   

2. Replace placeholder variables: Search and replace the following placeholders throughout the codebase:

   • <app_name_lower_case> - Your application name in lowercase (e.g., my-api)
   • <app_name_upper_case> - Your application name in uppercase (e.g., MY_API)

   Make sure to check all files, especially:

   • wrangler.toml
   • .github/workflows/deploy.yaml
   • src/swagger/config.js

3. Set up a new Git repository:

   # Remove existing Git history
   rm -rf .git
   
   # Initialize a new Git repository
   git init
   
   # Add your remote repository
   git remote add origin <your-new-repository-url>
   
   # Add all files
   git add .
   
   # Commit
   git commit -m "Initial commit from template"
   
   # Push to main branch
   git push -u origin main
   

4. Create development branches:

   # Create and push dev branch
   git checkout -b dev
   git push -u origin dev
   
   # Create and push playtest branch
   git checkout -b playtest
   git push -u origin playtest
   

Branching Strategy

Follow this workflow for code changes:

1. Feature Development:

   • Create feature branches from dev
   • Name format: feature/your-feature-name

2. Deployment Flow:

   • Playtest: Merge directly from feature branches for testing
   • Development: Submit Pull Requests from feature branches
   • Production: Submit Pull Requests from dev to main

Configuration

Database (D1)

The template comes with D1 database configuration. If you need to use it:

1. Create your D1 databases for each environment:

   create <app_name_lower_case>_dev
   create <app_name_lower_case>_playtest
   create <app_name_lower_case>_prod
   

2. Update the database IDs in wrangler.toml with the IDs generated from the commands above.

If you don't need D1, remove the d1_databases sections from wrangler.toml.

Storage (R2)

The template includes R2 bucket configuration. If you need to use it:

1. Create your R2 buckets for each environment:

   create <app_name_lower_case>-dev
   create <app_name_lower_case>-playtest
   create <app_name_lower_case>-prod
   

2. Update the bucket names in wrangler.toml.

If you don't need R2, remove the r2_buckets sections from wrangler.toml.

Authentication

The API comes with two authentication methods:

1. API Key Authentication: Using the X-Api-Key header
2. Bearer Token Authentication: Using the Authorization: Bearer <token> header

These are configured in the Swagger documentation and middleware. Do not modify the authentication mechanisms unless necessary.

API Documentation

The API documentation is generated using Swagger/OpenAPI. The configuration is modular and located in:

• src/swagger/config.js: Main configuration
• src/swagger/endpoints/: Individual endpoint definitions

When adding new endpoints:

1. Create a new file in src/swagger/endpoints/ for your endpoint
2. Export the endpoint configuration
3. Import and add it to src/swagger/config.js

Access the documentation at /api/<app_name_lower_case>/docs when the API is running.

Design Documentation

All design documentation should be maintained in the blueprint repository:

1. Create design documentation in the blueprint repository located at <app_name_lower_case>
2. Submit the design as a Pull Request to the blueprint repository
3. Once approved, add the link to the design file in docs/DESIGN.md

The docs/DESIGN.md file should contain a reference to the design document's location in the blueprint repository.

Code Structure Guidelines

• Keep files modular and under 100 lines
• Organize related functionality into separate modules
• Place shared logic in src/helpers/ or appropriate service directories
• Follow the existing pattern for new endpoints and services

Development

Local Development

This project uses Docker for local development to ensure consistency across environments:

# Start the local development server
docker compose up

# To run in detached mode
docker compose up -d

# To stop the server
docker compose down

The server will be available at http://localhost:8787.

Deployment

Deployments are handled automatically by GitHub Actions when pushing to the appropriate branches:

• Push to playtest → Deploys to Playtest environment
• Push to dev → Deploys to Development environment
• Push to main → Deploys to Production environment

License

MIT

Development Checklist

Follow this checklist when working on a new feature or issue:

• Define Issue with Acceptance Criteria - Issue ID
• Create one or more Tasks to Work on Issue Task ID
• Create/Update Design Documentation - Design DOcument Link
• Create PR for Design Documentation - PR ID
• Follow Steps in README to create your own project Repository ID
• Commit Code and test default code in all 3 environments - PlayTest Url
• Create feature branch for your issue -
• Write your own code Method Id /Url
• Test locally using docker compose
• Merge to playtest branch
• Test on Cloudflare
• Request PR to dev branch PR ID