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

Success

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

Exercises

1. Pick a free public API (like OpenWeather or REST Countries), use the documentation prompt to understand it, then build a small widget that fetches and displays one piece of data.
2. Add all four states to that widget — loading, success, error, and empty — using the "Handling API States" prompts, and manually trigger each one.
3. Move any API key out of frontend code into an environment variable / server-side route using the secure-setup prompt, then confirm the key is no longer visible in the browser.