Working with Netlify

Working with Netlify

If you're using Netlify for frontend hosting, you can easily proxy your API calls to your ArangoDB Foxx services using Netlify's redirect functionality. This allows you to serve your frontend and API from the same domain, avoiding CORS issues.

Basic Configuration

Netlify.toml Setup

Create a netlify.toml file in your frontend project root:

[build]
    base = "."
    publish = "./dist"
    functions = "netlify-functions/"

[[redirects]]
    from = "/api/*"
    to = "http://{YOUR_HOSTNAME}:8529/_db/{YOUR_DATABASE}/{YOUR_ENDPOINT}/:splat"
    status = 200
    force = true
    headers = {X-From = "Netlify", X-Api-Key = "some-api-key-string"}

Configuration Variables

Before deploying, replace these variables with your actual values:

• {YOUR_HOSTNAME} - The hostname where ArangoDB is running (e.g., api.yourapp.com)
• {YOUR_DATABASE} - ArangoDB database name where the Foxx service is installed
• {YOUR_ENDPOINT} - Endpoint where your Foxx services are mounted (e.g., api)

Example Configuration

For a typical setup, your netlify.toml might look like:

[build]
    publish = "dist"
    command = "npm run build"

[[redirects]]
    from = "/api/*"
    to = "https://api.yourapp.com:8529/_db/production/api/:splat"
    status = 200
    force = true
    headers = {X-From = "Netlify", X-Api-Key = "your-secure-api-key"}

# Optional: Redirect root API calls to documentation
[[redirects]]
    from = "/api"
    to = "/api/"
    status = 301

Local Development Configuration

For local development testing:

[[redirects]]
    from = "/api/*"
    to = "http://localhost:8529/_db/foxx-sandbox/api-dev/:splat"
    status = 200
    force = true
    headers = {X-From = "Netlify", X-Api-Key = "dev-api-key"}

Security with API Keys

Adding Header-based Protection

The X-Api-Key header provides a basic layer of protection. To implement this in your Foxx service, add the following middleware to your src/index.js:

const builder = require('./builder/index');
builder.init();

// API Key validation middleware
module.context.use((req, res, next) => {
    const apiKey = req.headers['x-api-key'];
    
    // Skip validation for health checks
    if (req.path === '/health' || req.path === '/status') {
        return next();
    }
    
    if (!apiKey || apiKey !== module.context.configuration.netlifyApiKey) {
        res.throw(401, 'Invalid or missing API key');
    }
    
    next();
});

Configuration in manifest.json

Add the API key configuration to your manifest.json:

{
  "configuration": {
    "netlifyApiKey": {
      "type": "string",
      "default": "your-default-api-key",
      "description": "API key for Netlify integration",
      "required": true
    }
  }
}

Environment-specific API Keys

Use different API keys for different environments:

// In your Foxx service
const expectedApiKey = module.context.configuration.netlifyApiKey;
const environment = module.context.configuration.environment || 'development';

// Log API key validation (remove in production)
if (environment === 'development') {
    console.log(`API Key validation: ${apiKey === expectedApiKey ? 'PASS' : 'FAIL'}`);
}

Advanced Netlify Configuration

Multiple API Endpoints

If you have multiple Foxx services or versions:

# API v1
[[redirects]]
    from = "/api/v1/*"
    to = "https://api.yourapp.com:8529/_db/production/api-v1/:splat"
    status = 200
    force = true
    headers = {X-From = "Netlify", X-Api-Key = "v1-api-key", X-Version = "v1"}

# API v2
[[redirects]]
    from = "/api/v2/*"
    to = "https://api.yourapp.com:8529/_db/production/api-v2/:splat"
    status = 200
    force = true
    headers = {X-From = "Netlify", X-Api-Key = "v2-api-key", X-Version = "v2"}

# Default to latest version
[[redirects]]
    from = "/api/*"
    to = "https://api.yourapp.com:8529/_db/production/api-v2/:splat"
    status = 200
    force = true
    headers = {X-From = "Netlify", X-Api-Key = "v2-api-key", X-Version = "v2"}

Branch-specific Deployments

For preview deployments with different API endpoints:

# Production (main branch)
[[redirects]]
    from = "/api/*"
    to = "https://api.yourapp.com:8529/_db/production/api/:splat"
    status = 200
    force = true
    headers = {X-From = "Netlify", X-Api-Key = "production-key"}
    conditions = {branch = ["main"]}

# Staging (develop branch)
[[redirects]]
    from = "/api/*"
    to = "https://staging-api.yourapp.com:8529/_db/staging/api/:splat"
    status = 200
    force = true
    headers = {X-From = "Netlify", X-Api-Key = "staging-key"}
    conditions = {branch = ["develop"]}

# Feature branches (preview deployments)
[[redirects]]
    from = "/api/*"
    to = "https://dev-api.yourapp.com:8529/_db/development/api/:splat"
    status = 200
    force = true
    headers = {X-From = "Netlify", X-Api-Key = "dev-key"}

Testing Your Setup

Local Testing with Netlify CLI

Install and use the Netlify CLI for local testing:

# Install Netlify CLI
npm install -g netlify-cli

# Start local development with redirects
netlify dev

# Test your API endpoints
curl http://localhost:8888/api/health

Deployment Testing

After deploying to Netlify:

# Test your deployed API
curl https://yourapp.netlify.app/api/health

# Test with API key (should work)
curl -H "X-Api-Key: your-api-key" https://yourapp.netlify.app/api/users

# Test without API key (should fail)
curl https://yourapp.netlify.app/api/users

GitHub Actions Integration

You can automate Netlify deployments alongside your Foxx service deployments. Here's an example workflow:

name: Deploy to Netlify
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      # Deploy Foxx service first
      - name: Deploy Foxx Service
        run: |
          # Your Foxx deployment commands here
          
      # Then deploy frontend to Netlify
      - name: Deploy to Netlify
        uses: nwtgck/actions-netlify@v2
        with:
          publish-dir: './dist'
          production-branch: main
          production-deploy: true
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

Best Practices

1. Security

• Use strong, unique API keys for each environment
• Rotate API keys regularly
• Don't commit API keys to version control
• Use Netlify environment variables for sensitive data

2. Performance

• Consider caching strategies for API responses
• Use appropriate cache headers in your Foxx service
• Monitor API response times

3. Monitoring

• Set up monitoring for your API endpoints
• Use Netlify's analytics to track API usage
• Implement health checks and status endpoints

4. Error Handling

• Provide clear error messages from your API
• Handle network errors gracefully in your frontend
• Set up proper error logging

Troubleshooting

Common Issues

1. CORS Errors:

   • Ensure you're using the same domain (Netlify's proxy handles this)
   • Check that your Foxx service doesn't set conflicting CORS headers

2. API Key Failures:

   # Test API key validation
   curl -H "X-Api-Key: wrong-key" https://yourapp.netlify.app/api/health
   # Should return 401 Unauthorized

3. Redirect Not Working:

   • Check netlify.toml syntax
   • Verify the to URL is accessible
   • Test with netlify dev locally

4. Database Connection Issues:

   • Verify your ArangoDB server is accessible from the internet
   • Check firewall settings
   • Ensure database and user credentials are correct

Debug Commands

# Check Netlify deployment logs
netlify logs

# Test redirects locally
netlify dev

# Check site configuration
netlify status

# View site information
netlify sites:list

Resources

• Netlify Redirects Documentation
• Netlify CLI Documentation
• Netlify Environment Variables
• ArangoDB Security Best Practices

Migration Notes

Note: This documentation assumes you're using the updated project structure with GitHub Actions for deployment and the new test locations (tests/hurl/). The integration patterns remain the same, but deployment workflows have been modernized.