What Is a REST API? A Plain-English Explainer for New Developers

Most web apps are conversations between two programs. Your browser asks for something; a server answers. A REST API is the agreed way those two sides talk: which addresses exist, which actions you can take, what the data looks like, and how failures get reported. The acronym sounds formal, but the idea is practical. Once you can read an endpoint, a verb, a status code, and a JSON body, you can debug most API calls without guessing.

Start With Resources, Not Magic

REST treats things as resources. A user is a resource. An order is a resource. An article is a resource. An endpoint is the address where that resource lives. If you have used a library catalogue, you already know the pattern: one label points to the whole shelf, another points to a single book.

In an API, a collection endpoint might look like /articles. A single item endpoint might look like /articles/42. The first means “the articles collection”; the second means “article number 42.” That is a convention, not a law of REST, but it makes an API easier to read.

Endpoints also carry query parameters. /articles?category=tutorials&limit=10 asks for a filtered collection: tutorials, at most ten of them. The base URL tells you which server you are talking to. The path tells you which resource you want. The query string narrows the request.

Good endpoints describe nouns, not actions. If you see /getArticleById?id=42, the action is stuck in the URL. If you see GET /articles/42, the action lives in the HTTP verb and the URL stays focused on the resource. Both can work, but the second is easier to extend and reason about.

Resources can also nest. /users/7/orders reads as “the orders that belong to user 7.” Nesting is useful when one resource only makes sense inside another, but deep nesting gets clumsy. If a path grows into /users/7/orders/88/items/3/reviews, it may be time to give reviews their own top-level endpoint. The goal is clarity, not cleverness.

HTTP Verbs Tell the Server What You Want

The verb is the method attached to the request. It tells the server what you intend to do with the resource. The same endpoint can behave differently depending on the verb, which is why GET /articles/42 and DELETE /articles/42 are not the same request.

• GET retrieves data. It should not change anything on the server. Reloading a GET request should be safe.
• POST creates a new resource or submits data for processing. Sending the same POST twice may create two records, so be careful with retries.
• PUT replaces a resource, or creates it at a known address. You send the full representation you want to exist.
• PATCH updates part of a resource. Send only the fields that change.
• DELETE removes a resource. A successful DELETE often returns no body at all.

Think of a request as a note handed to a records clerk. The endpoint is the filing cabinet and folder. The verb is the instruction: fetch this folder, add a new sheet, replace this sheet, change one line, or remove the sheet.

Use verbs for intent. Avoid /deleteArticle?id=42 when DELETE /articles/42 says the same thing more clearly. That convention matters when you read logs, write tests, or hand the API to another developer.

One practical detail: GET, PUT, and DELETE are usually idempotent, meaning repeating the same request should leave the server in the same state. POST is usually not idempotent: sending the same “create article” request twice can create two articles. If you are retrying a POST after a timeout, check whether the API supports an idempotency key or confirm the record was not already created. That small habit prevents duplicate orders, duplicate signups, and confusing support tickets.

PATCH can be idempotent or not, depending on the operation. Sending {"status": "published"} twice gives the same result. Sending {"views": 1} as an increment might not. Read the API documentation for the exact behavior.

Status Codes Are the Server’s Short Answer

Every HTTP response starts with a three-digit status code. Read it before you read the body. The first digit groups the answer: 2xx means success, 3xx means a redirect or cached response, 4xx means the request has a problem, and 5xx means the server has a problem.

Some codes you will meet often:

• 200 OK: the request worked and there is a response body.
• 201 Created: a new resource was created. The response often includes its ID or location.
• 204 No Content: the request worked, but there is nothing to return. Common after DELETE.
• 400 Bad Request: the request is malformed or missing required data.
• 401 Unauthorized: authentication is missing or invalid. Despite the name, it usually means “who are you?”
• 403 Forbidden: the server knows who you are, but you are not allowed to do this.
• 404 Not Found: the endpoint or resource does not exist.
• 409 Conflict: the request clashes with the current state, such as creating a duplicate username.
• 500 Internal Server Error: something failed on the server side. Your request may be fine.

That difference between 4xx and 5xx saves time. A 404 usually means you mistyped a path or used the wrong ID. A 500 means retrying the same request may not help; the server needs attention. A 401 means check your token or login. A 403 means check permissions, not credentials.

Error responses often include a JSON body with more detail, such as {"error": "title is required"}. Read the status code first, then the body. A useful API gives you both the category and the specific field or rule that failed.

JSON Payloads: The Data Inside the Envelope

Most modern REST APIs exchange data as JSON, which stands for JavaScript Object Notation. Do not let the name scare you. JSON is a simple text format for structured data: objects in curly braces, arrays in square brackets, and values that are strings, numbers, booleans, or null.

A response might look like this:

{"id": 1, "title": "What Is a REST API?", "published": true, "tags": ["api", "beginner"]}

The outer braces hold an object. Each key is a string in double quotes. The colon separates the key from its value. The tags key holds an array, so it can carry several values. That structure is why JSON is easy to read in a terminal and easy to parse in code.

Pay attention to where the JSON sits. A GET request usually has no request body; the data you send travels in the URL or headers. POST, PUT, and PATCH requests usually do include a body, and that is where the JSON payload goes. If a POST returns 400, check the body first: missing fields, wrong types, or invalid JSON are common causes. If it returns 415, the server does not accept the format you sent, so check the Content-Type header. A create request might send a body like {"title": "My first API call", "published": false} while the server supplies the ID and timestamps.

JSON has strict rules. Keys and string values use double quotes, not single quotes. Trailing commas are not allowed. A missing brace can turn a good request into a vague error, so when a payload fails, paste it into a JSON validator before blaming the endpoint.

Headers Carry the Fine Print

Headers are metadata attached to a request or response. They do not usually hold the resource itself; they describe how to handle it. Two headers show up constantly. Content-Type tells the server what format the request body uses, such as application/json. Accept tells the server what format the client wants back. If you send JSON without saying so, some servers will reject the request even though the body looks correct.

Authorization is how many APIs carry credentials. You will often see a header like Authorization: Bearer abc123. The token identifies the caller and carries permissions, but it is not part of the URL. Keep tokens out of query strings, logs, and screenshots. If a request returns 401, check whether the header is present and the token is current. If it returns 403, the token may be valid but lack the required role.

Other headers appear for caching, request IDs, rate limits, and content length. You do not need to memorize them all. Learn to scan the response headers when something behaves strangely. A rate-limit header, for example, can explain why requests suddenly return 429 Too Many Requests, even though the same call worked a minute ago.

A Small Walkthrough: Reading One API Call

Suppose you are building a small blog and the API exposes /articles. A create request might look like a POST /articles with a JSON body containing a title and body. The server responds with 201 Created, returns the new article including its id, and may include a Location header pointing to /articles/42. That response tells you three things at once: the request succeeded, a resource now exists, and you know the address for future calls.

Next, a client asks for it with GET /articles/42. The response is 200 OK and a JSON object. To change only the title, use PATCH /articles/42 with a body like {"title": "A clearer title"}. To remove it, use DELETE /articles/42 and expect 204 No Content. If you request it again after deletion, expect 404 Not Found. That sequence is the shape of many API conversations: create, read, update, delete.

When a call fails, debug in a fixed order. First, check the method and URL. Second, read the status code. Third, inspect the request headers, especially Content-Type and Authorization. Fourth, validate the JSON body. Fifth, read the response body for a specific error message. That order catches most beginner mistakes before they turn into an afternoon of guesswork.

REST is a set of conventions, not a single product. Two REST APIs can both be “RESTful” and still differ in details. Always read the documentation for the API in front of you.

The payoff is practical. Once you recognize resources, verbs, status codes, headers, and JSON, an unfamiliar API stops looking like a wall of URLs. It becomes a set of predictable requests and responses that you can test, read, and debug one call at a time.

Photo: Brett Sayles / Pexels