APIs for designers: what they are and why your app needs them

What does an API do, in simple words?

Think of a socket. You do not need to know how electricity is generated to use a lamp; the socket just follows a standard. An API works in a similar way: the program asking for data does not need to know the service’s internal structure, only the format the service defines. So a “Search” button can talk to a database that changed inside without the interface noticing.

MDN defines APIs as constructs that let developers create complex functionality more easily, because they abstract complex code away and provide simpler syntax in its place (MDN, Introduction to client-side web APIs). The same page separates two kinds:

• Browser APIs: built into the browser. One example is the Web Storage API, which stores name/value pairs on the user’s device.
• Third-party APIs: not built into the browser; you reach them over the internet. MDN’s example is the Google Maps API, which lets you show an interactive map on your site.

An AI service is a third-party API: your interface sends it some text and gets an answer back.

How does a request travel?

The web uses the HTTP protocol, which works with a client-server model. According to MDN, the browser is always the one that starts the request; the server only answers (MDN, Overview of HTTP). Each message has concrete parts:

What do status codes mean?

Codes are grouped in families, and the family already tells you what kind of message to design. This table summarizes the most useful ones from MDN’s catalog (MDN, HTTP response status codes):

Watch 401 and 403: although the standard says “unauthorized”, MDN clarifies that 401 means “unauthenticated” and 403 means the server knows who you are but refuses access. One message says “sign in”; the other says “you do not have permission”.

429 deserves attention in AI products, because model services usually limit how many requests you can make. MDN calls this mechanism rate limiting and explains that the response may carry a Retry-After header with the suggested wait time (MDN, 429 Too Many Requests). When it exists, your message can say how long to wait.

What happens when a call fails or is repeated?

An impatient user taps the button twice, or the network drops right after sending. That raises a question the design must answer: is it safe to repeat the request?

MDN calls a method idempotent when sending it once has the same effect as sending it several times. GET, PUT and DELETE are; POST is not guaranteed to be: MDN’s example is that a repeated POST /add_row adds several rows (MDN, Idempotent).

In design, this translates into three decisions:

• Reading is safe to retry. A “Retry” button on a lookup screen carries no risk.
• Creating or charging is not. If a purchase fails because of a network drop, the server may have processed it anyway. Ask the technical team how double charges are prevented before you add a retry button.
• Disable the button while the request is in progress. It is the simplest way to avoid duplicate submissions.

Why does it matter to a designer working with AI?

Because an AI interface almost never has the model inside. It sends the question through an API to an external service and shows the answer. That has design consequences:

• The answer can be slow. Each call needs a loading state (loading states in AI) and, if the service supports it, the answer can be shown as it arrives (response streaming). To understand why it takes time, see LLM latency.
• It can fail or arrive incomplete. Each state of the connection needs its own screen: loading, answer, error and retry.
• Each call can cost money. Many AI services charge by usage; see cost per token. A button that fires unlimited calls is also a cost decision.
• Keys do not belong in the browser. The keys that authorize those calls must not live in the code the user receives. In Beyond Vibe Coding, Addy Osmani warns that vibe coding is fun until you start leaking database credentials in the client (Osmani, Beyond Vibe Coding). See environment variables and secrets.

Example

Illustrative example: a designer builds a page where the user types a city and sees the weather. The interface sends a GET to a service with the city in the path. When the service answers 200, it shows the temperature. If it answers 404, it shows “We could not find that city, check the spelling”. If it answers 429, it shows “There are many requests right now, wait a few seconds”. If it answers 500, it shows “The weather service is unavailable, try again in a few minutes” with a retry button. Four situations, four messages, all coming from the status code.

How to apply it tomorrow

1. List the screens in your prototype that depend on an external service. For each one, write what it requests, what it returns and what happens if it fails.
2. Design at least four states for each call: loading, success, request error (4xx) and server error (5xx). Draw them before asking for the implementation.
3. Ask the AI to show the real API response in the console, with an example, before connecting the screen. That way you will know which fields actually exist.
4. Test the screen by disconnecting the network on purpose. If the error message has no next step, the screen is not finished.
5. Ask the technical team what happens if the user sends the same request twice.

Common mistakes

• Showing the same error message for a 404 as for a 500.
• Saying “you do not have permission” when the real problem is an expired session (401).
• Calling a service from the browser with a secret key.
• Not designing the loading state for a response that takes time.
• Adding a retry button to an action that creates or charges, without confirming that repeating it is safe.
• Confusing an API with a database: the API is the door, not the storage room.

Sources

• MDN Web Docs, “Introduction to client-side web APIs”: https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Introduction
• MDN Web Docs, “Overview of HTTP”: https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview
• MDN Web Docs, “HTTP response status codes”: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status
• MDN Web Docs, “429 Too Many Requests”: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/429
• MDN Web Docs, “Idempotent”: https://developer.mozilla.org/en-US/docs/Glossary/Idempotent
• Addy Osmani, “Beyond Vibe Coding”: https://beyond.addy.ie/