4 min read
Working with APIs
APIs let your app talk to other services — fetching weather data, saving to databases, or integrating AI. This guide covers the concepts designers need to know.
What’s an API?
The restaurant analogy
- You (the customer) want food
- The menu shows what’s available
- The waiter takes your order to the kitchen
- The kitchen prepares and sends back your food
An API is the waiter. Your app makes requests, and the API returns data.
In practice
- Your app asks: “Give me the weather for San Francisco”
- The weather API processes the request
- The API responds with temperature, conditions, etc.
- Your app displays the information
Reading API Documentation
What to look for
- Base URL: Where to send requests (
api.weather.com) - Endpoints: Specific resources (
/forecast,/current) - Methods: GET (read), POST (create), PUT (update), DELETE (remove)
- Parameters: What info to include (
city=SF&units=celsius) - Response format: What you get back (usually JSON)
Example documentation prompt
I found this API: [API name/URL]
Help me understand how to use it.
What endpoints are available?
What do I need to send?Authentication
Most APIs require authentication:
- API keys: A secret string you include with requests
- OAuth: Login-based authentication
- None: Public APIs (rare)
Common API Patterns
Fetching data (GET)
Fetch the current weather from [API] and display it.
Show temperature, conditions, and humidity.Sending data (POST)
Send the form data to [API] when the user submits.
Handle success and error responses.Real-time updates
Poll [API] every 30 seconds for updates.
Update the UI when new data arrives.Useful APIs for Designers
Weather
- OpenWeather, WeatherAPI
- Good for dashboards, outdoor apps
AI/ML
- OpenAI, Anthropic, Replicate
- Text generation, image generation, analysis
Design tools
- Figma API, Unsplash, Pexels
- Access design files, stock images
Data
- REST Countries, Open Library
- Pre-built datasets
Productivity
- Notion, Airtable, Google Sheets
- Read/write structured data
Example Integrations
Weather widget
Add a weather widget that shows current conditions.
Use OpenWeather API.
Fetch data for [city] on load.
Show temperature and an icon for conditions.AI integration
Add a text generation feature using OpenAI.
User types a prompt, clicks generate,
and the response appears below.
Include loading state.Image search
Add image search using Unsplash API.
Search input at top.
Show results in a grid.
Clicking an image selects it.API Keys and Security
Keep keys secret
- Never put API keys in client-side code (visible to users)
- Use environment variables
- Use server-side routes or serverless functions
Prompting for secure setup
Set up the API key securely.
Don't expose it in the frontend code.
Use environment variables.Rate limits
- Most APIs limit how many requests you can make
- Handle rate limit errors gracefully
- Cache responses when appropriate
Handling API States
Loading
Show a loading indicator while the API request is in progress.Success
Display the data in [format] when the request succeeds.Error
If the request fails, show a friendly error message.
Include a retry button.Empty
If the API returns no results, show an empty state
with helpful suggestions.Debugging API Issues
Request not working
The API request isn't working.
Here's what I'm trying: [describe]
Here's the error: [paste error]Unexpected data
The API returns data but it's not what I expected.
Here's what I got: [paste response]
Here's what I expected: [describe]Authentication failing
I'm getting an authentication error from [API].
Here's my setup: [describe]
Error message: [paste]What You’ll Learn
- What APIs are and how they work
- Reading API documentation
- Common APIs useful for designers
- Security best practices with API keys
- Handling loading, error, and success states
- Debugging common API issues