Integrating External APIs

​

Overview

​

Prerequisites

• An active Stardeck app
• Familiarity with environment variables in Stardeck
• An account with the API service you want to use

​

Popular API Services

• Payment Gateways: Stripe, Omise, PayPal - See detailed payment integration guide
• Weather: OpenWeatherMap, WeatherAPI, Tomorrow.io
• Maps & Location: Google Maps, Mapbox, OpenStreetMap
• Email: SendGrid, Mailgun, Resend
• SMS: Twilio, MessageBird, Vonage
• AI/ML: OpenAI, Anthropic, Google Gemini
• Social Media: Twitter API, Instagram API, LinkedIn API

​

Setting Up OpenWeatherMap (Example)

​

Creating an Account

1. Go to openweathermap.org and click Sign In or Sign Up
2. Complete the registration process
3. Verify your email address
4. You’ll be automatically enrolled in the Free tier

​

Getting Your API Key

1. After signing in, go to your account page by clicking your username
2. Navigate to the API keys tab
3. You’ll see a default API key already created, or you can create a new one
4. Copy your API key (starts with a long alphanumeric string)

​

Understanding API Limits

• Free tier: 1,000 calls/day, 60 calls/minute
• Data: Current weather, 5-day forecast, weather maps
• Updates: Weather data updates every 10 minutes

​

Setting Up Other Common APIs

​

Google Maps API

1. Go to Google Cloud Console
2. Create a new app or select existing
3. Enable Maps JavaScript API and Geocoding API
4. Go to Credentials and create an API key
5. Restrict the key by HTTP referrer (for security)

​

SendGrid (Email)

1. Sign up at sendgrid.com
2. Verify your sender email address
3. Go to Settings > API Keys
4. Create an API key with appropriate permissions
5. Copy the key (shown only once)

​

Twilio (SMS)

1. Sign up at twilio.com
2. Get your free trial phone number
3. Find your Account SID and Auth Token in the dashboard
4. Copy both credentials

​

Configuring Environment Variables in Stardeck

​

Adding API Keys

1. Open your app in the Stardeck dashboard
2. Click the Settings button (gear icon)
3. Navigate to the Environment Variables tab

​

OpenWeatherMap Configuration

​

API Key (Non-Secret)

• Key: WEATHER_API_KEY
• Value: Your OpenWeatherMap API key
• Secret Variable: Off (unchecked)
• Deployment Targets: Select Sandbox for testing

​

Google Maps Configuration

• Key: GOOGLE_MAPS_API_KEY
• Value: Your Google Maps API key
• Secret Variable: Off (for client-side use) or On (for server-side)
• Deployment Targets: Select Sandbox

​

SendGrid Configuration

• Key: SENDGRID_API_KEY
• Value: Your SendGrid API key (starts with SG.)
• Secret Variable: On (checked) - always keep email API keys secret
• Deployment Targets: Select Sandbox

​

Twilio Configuration

• Key: TWILIO_ACCOUNT_SID
• Value: Your Account SID
• Secret Variable: Off
• Key: TWILIO_AUTH_TOKEN
• Value: Your Auth Token
• Secret Variable: On (checked)
• Key: TWILIO_PHONE_NUMBER
• Value: Your Twilio phone number (e.g., +15551234567)
• Secret Variable: Off

​

Using the AI Agent to Build API Integrations

​

Weather App with Current Conditions

Build a weather app that shows current weather for any city.

Requirements:
- Search box where users can enter a city name
- Display current temperature, weather condition, humidity, and wind speed
- Use OpenWeatherMap API with WEATHER_API_KEY environment variable
- Show a weather icon matching the condition
- Handle invalid city names gracefully

​

Weather Dashboard with Forecast

Create a weather dashboard for my local business showing the 5-day forecast.

Requirements:
- Display weather for my city (Bangkok) automatically
- Show 5-day forecast with daily high/low temperatures
- Use WEATHER_API_KEY to fetch data from OpenWeatherMap
- Update automatically every hour
- Show weather icons for each day

​

Location-Based Services with Maps

Add a store locator to my website with an interactive map.

Requirements:
- Display Google Map with markers for my 5 store locations
- Use GOOGLE_MAPS_API_KEY for the map
- Show store details (name, address, hours) when clicking markers
- Add a search box to find nearest store by address
- Mobile-responsive map

​

Email Notifications

Send confirmation emails to customers when they submit the contact form.

Requirements:
- Use SendGrid with SENDGRID_API_KEY to send emails
- Email template with our company logo and branding
- Include customer's message and contact details
- Send copy to our support email
- Handle send failures gracefully

​

SMS Alerts

Send SMS notifications to customers when their order is ready for pickup.

Requirements:
- Use Twilio with TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN
- Send SMS from TWILIO_PHONE_NUMBER
- Message format: "Your order #[ORDER_ID] is ready for pickup at [LOCATION]"
- Store SMS delivery status in database
- Only send to valid phone numbers

​

Multi-API Integration

Build a travel planning tool that combines weather and map data.

Requirements:
- Let users search for a destination
- Show the location on Google Maps using GOOGLE_MAPS_API_KEY
- Display current weather and 5-day forecast using WEATHER_API_KEY
- Show nearby attractions on the map
- Save favorite destinations to database

​

Tips for Effective Prompting

1. Name your environment variables clearly - The agent will use them automatically
2. Specify data to display - Be clear about what information you want to show
3. Mention error handling - APIs can fail, timeout, or return errors
4. Request caching - Consider asking to cache API responses to save costs
5. Be specific about frequency - How often should data refresh?

​

Testing Your Integration

​

Testing Weather API

• Valid city: Try “London” or “Bangkok”
• Invalid city: Try “XYZ123” to test error handling
• Special characters: Try “São Paulo” to test encoding
• Rate limits: Make multiple rapid requests to test rate limit handling

​

Testing Email/SMS APIs

• Use your personal email/phone during development
• Check spam folder for test emails
• Verify API call limits on dashboard
• Test with invalid recipients to check error handling

​

Monitoring API Usage

1. Check your API provider’s dashboard regularly
2. Monitor daily usage against limits
3. Set up alerts for high usage
4. Review error logs for failed requests

​

Best Practices

​

Security

• Mark sensitive keys as secret - Email, SMS, and payment APIs should always be secret
• Restrict API keys - Use HTTP referrer or IP restrictions when available
• Rotate keys regularly - Change API keys periodically
• Never commit keys to git - Always use environment variables

​

Performance

• Cache API responses - Don’t fetch the same data repeatedly
• Implement rate limiting - Respect API provider’s limits
• Use webhooks when available - More efficient than polling
• Handle errors gracefully - APIs can be temporarily unavailable

​

Cost Management

• Monitor usage - Check dashboards regularly
• Set spending limits - Use billing alerts
• Choose the right tier - Upgrade only when needed
• Optimize requests - Fetch only what you need

​

Going Live with Production

​

Moving to Production

1. Upgrade API plan if needed - Check if free tier is sufficient
2. Get production API keys - Many services have separate prod keys
3. Add production environment variables in Stardeck
4. Set Deployment Targets to Production
5. Configure webhooks - Update webhook URLs to production domain
6. Test thoroughly - Verify all API integrations work in production

​

Production Checklist

• Production API keys obtained
• Billing/payment method configured with API provider
• Usage alerts set up
• API keys configured in Stardeck production environment
• Error monitoring in place
• Rate limits appropriate for production traffic
• Webhook endpoints verified
• Documentation for team members

​

Additional Resources

​

Weather APIs

• OpenWeatherMap Documentation
• WeatherAPI Docs

​

Maps & Location

• Google Maps Platform
• Mapbox Documentation

​

Communication

• SendGrid Documentation
• Twilio Documentation

​

AI & ML

• OpenAI API Documentation
• Anthropic API Documentation