Let’s translate them into plain English.
This glossary uses a simple analogy: an API is like ordering food at a restaurant. You (a client) ask for something, the kitchen (a server) prepares it, and you get a result back.
Client, server, endpoint: who’s talking to who?
Client: The thing making the request. On iOS Safari, the “client” is often the website you opened (its JavaScript), not Safari itself.
Server: The system that receives the request and sends back a response. Think “the kitchen.”
Endpoint: A specific URL that does one job (like “/orders” or “/users/123”). Think “the menu item you’re ordering,” not the whole restaurant.
- Base URL: The restaurant location (domain), like https://api.example.com.
- Path: The menu section and item, like /v1/orders.
- Query parameters: The customizations, like ?status=open&limit=10.
A fast way to sanity-check an endpoint is to read the URL left-to-right and ask: “Which restaurant? Which menu item? Any custom options?”
Request vs response: the “ask” and the “answer”
Request: What the client sends to the server. In the restaurant analogy: your order.
Response: What the server sends back. In the analogy: the food (and the receipt).
- Headers (metadata)
- Body (the main content, sometimes empty)
In many API problems, the “body” looks fine, but a missing header (like auth) is what breaks everything.
HTTP methods: what kind of “order” are you placing?
GET: “Please show me.” Used for reading data (view the menu, fetch your order status). Usually no body.
POST: “Please create this.” Used for creating something new (place an order). Commonly has a body.
PUT / PATCH: “Please update this.” Like changing your order.
- PUT often means “replace the whole thing.”
- PATCH often means “change just these fields.”
DELETE: “Please remove this.” Like canceling an order.
If you’re seeing “Method Not Allowed,” it’s often the right URL with the wrong method.
Status codes: the kitchen’s quick shorthand
2xx: Success.
- 200 OK: Here’s the data.
- 201 Created: Created something new.
- 204 No Content: Success, but nothing to show.
3xx: Redirects. “That moved over there.”
4xx: Client-side issue (your request is the problem).
- 400 Bad Request: The server couldn’t understand what you sent (often invalid JSON).
- 401 Unauthorized: Missing/invalid login token.
- 403 Forbidden: You are logged in, but not allowed.
- 404 Not Found: Wrong URL (or the thing doesn’t exist).
- 429 Too Many Requests: Slow down (rate limit).
5xx: Server-side issue (the kitchen is having a bad day).
- 500: Generic server error.
- 502/503/504: Often proxy/load balancer/timeouts—common when things are overloaded.
A practical habit: treat 4xx as “fix my request,” and 5xx as “retry or escalate.”
Headers and content types: the “labels on the package”
Headers are small key/value lines that describe how to interpret the request/response.
- Content-Type: What format is in the body (commonly application/json).
- Accept: What formats the client can read.
- Authorization: Proof you’re allowed (token, API key, etc.).
- Cache-Control: Whether the client should cache it.
Restaurant analogy: if the body is “the meal,” headers are “gluten-free,” “deliver hot,” and “order number.”
JSON, schema, and validation: what the data “should look like”
JSON: The most common way APIs send structured data (objects and arrays). It’s like a neatly labeled takeout container.
Schema: The expected shape of that JSON. For example: which fields exist, which are required, and what types they are.
Validation: The server checking whether your request matches the schema.
- If validation fails, you’ll often see 400 plus an error like “email must be a string.”
- If you’re missing required fields, you’ll often get a list of what’s missing.
A beginner-friendly move: when something fails, compare your JSON keys to the docs—spelling and nesting mistakes are extremely common.
Auth terms: API key vs token vs session (who’s allowed to order?)
Authentication: Proving who you are.
Authorization: Proving what you’re allowed to do.
- API key: Like a simple membership card number. Easy to use, but needs careful handling.
- Bearer token: A short-lived “wristband” you show with each request (often in the Authorization header).
- Session cookie: A “claim ticket” the browser keeps and sends automatically to the same site.
In iOS Safari specifically, cookies and tracking protections can affect session-based auth more than token-based auth, especially across subdomains.
CORS, same-origin, and preflight: why it works in one place but not in Safari
Same-origin policy: Browsers restrict web pages from calling other origins freely. Origin roughly means scheme + domain + port.
CORS (Cross-Origin Resource Sharing): The server’s way of saying, “It’s okay for that other site to call me.”
Preflight: A browser “permission check” request (often an OPTIONS request) before the real request.
- If you see CORS errors, the server is missing the right Access-Control-Allow-* headers.
- If a request works in a native app or from your server but fails in Safari, CORS is a top suspect.
Restaurant analogy: you can’t just walk into any kitchen. CORS is the kitchen explicitly allowing your particular delivery service to place orders.
Rate limits, pagination, and timeouts: the “real world” constraints
Rate limit: You can only place so many requests in a time window (often triggers 429).
Pagination: Big lists are sent in chunks (pages). Look for limit, cursor, page, or next fields.
Timeout: The request took too long, so the client or a proxy gave up (often 504).
- If you’re fetching lists in Safari, pagination prevents slow pages and huge downloads.
- If you’re hitting rate limits, add backoff (wait and retry) and reduce repeated calls.
These aren’t “bugs” as much as rules for keeping the service stable.
Quick checklist: when an API call fails in iOS Safari
- URL: right domain + right path + right query params?
- Method: GET vs POST vs PATCH correct?
- Status code: 4xx (your request) or 5xx (server/proxy)?
- Headers: Content-Type, Accept, Authorization present and correct?
- Body: valid JSON (no trailing commas), correct field names and nesting?
- Auth type: cookie session vs token—does Safari have what it needs?
- CORS: does the response include Access-Control-Allow-Origin (and friends)?
- Limits: rate limit (429), pagination needed, or timeout?
If you can answer those eight items, you can usually describe the problem clearly—even before you fix it.
Takeaway: learn the “small vocabulary” and everything gets easier
You don’t need to memorize every API detail up front. If you understand request/response, methods, status codes, headers, auth, JSON, and CORS, you can read most API docs and interpret most errors you’ll run into from iOS Safari.