What is it?
An API (application programming interface) is a contract: inputs, outputs and rules that let one program use another. On the web, that often means sending an HTTP request to a URL and receiving JSON (REST APIs for Application Development, JSON Fundamentals for API Work). A "model API" is just an API specialised for generating tokens or embeddings.
Why it matters
AI products are API sandwiches: browser → your API → model API → maybe Gmail API. Clarity about each boundary keeps secrets and permissions in the right place (API Authentication: Keys, Sessions and OAuth).
How to do it
When you design an API:
- Name resources and actions clearly.
- Document request and response JSON.
- Pick auth (API Authentication: Keys, Sessions and OAuth).
- Define error codes and messages.
- Version when breaking changes appear.
When you consume an API: read auth docs, use timeouts, validate responses, handle rate limits.
Example
Your UI calls POST /api/chat with { "message": "…" }. Your server calls the vendor chat API. Both are APIs; only the server knows the vendor key. MCP may wrap APIs for agent discovery, but the underlying service is still an API.
When to use it
Expose an API whenever another program (your frontend, a partner, an agent tool host) needs stable programmatic access. Use a UI-only flow for purely human tasks.
Practical notes
APIs can be public, partner-only or private to your frontend. Each level needs different auth and abuse controls. Good docs include example requests, error bodies and rate limits. For AI systems, your API is also what agent tools call — so stability and clear errors matter twice. Avoid breaking JSON field names casually; add fields additively. If you must break, version the path ('/v1', '/v2'). Remember that MCP servers and SDKs usually sit on top of APIs rather than replacing them (MCP vs API: What's the Difference?). When learning, call a simple public JSON API with curl, then recreate the call in Python or JavaScript. Work through one real request end to end, write down the failure modes you observed, and add a regression test so the next change does not silently drop validation, auth, or logging. Prefer boring, reviewable code over a clever abstraction until the second or third product needs the same pattern. Work through one real request end to end, write down the failure modes you observed, and add a regression test so the next change does not silently drop validation, auth, or logging. Prefer boring, reviewable code over a clever abstraction until the second or third product needs the same pattern. Work through one real request end to end, write down the failure modes you observed, and add a regression test so the next change does not silently drop validation, auth, or logging. Prefer boring, reviewable code over a clever abstraction until the second or third product needs the same pattern.
Common mistakes
- Calling everything an API when you mean "the website form".
- No error contract — clients cannot recover.
- Equating MCP with "not an API" (MCP vs API: What's the Difference?).