What Is a REST API? HTTP Methods, Endpoints, and Status Codes Explained

Behind web apps and smartphone apps, communication is constantly happening to fetch the data shown on screen and to send what you enter. The mechanism that serves as the gateway for that communication is an API, and the most widely used design style today is the REST API. This article explains, step by step, what an API is, what kind of approach REST is, and how HTTP methods, status codes, and JSON exchanges work.

What Are an API and REST

An API (Application Programming Interface) is a "gateway" or "set of agreements" for software to interact with other software. For example, a weather app does not hold meteorological data itself; it asks a weather service's API to "tell me the weather for this area" and receives the result. Thanks to APIs, you can borrow data and features through a defined procedure without knowing the other side's internal structure.

REST (REpresentational State Transfer) is an approach and style that says we should design that API by using the mechanisms of the Web (HTTP) plainly and directly. An API built along the REST approach is called a REST API. REST has several principles, but the two beginners should grasp first are these.

• Resource-oriented: treat the targets of operations as resources such as "user," "article," or "order," and assign a URL (address) to each.
• Stateless: assume the server does not remember previous exchanges, and include everything a single request needs in that one request. This makes it easy to add servers and scale.

In other words, a REST API is a simple, easy-to-understand mechanism that expresses operations by combining "which resource (URL)" with "what to do (HTTP method)."

HTTP Methods: GET/POST/PUT/DELETE

In a REST API, you express "what you want to do" to a resource with an HTTP method. The four representative ones roughly correspond to CRUD (Create, Read, Update, Delete), the basic operations on data.

GET is the most commonly used method; it only reads data and does not change the target. Because the result does not change no matter how many times you run it (no side effects), typing a URL into the browser's address bar is also a GET. POST sends new data to create something and is used for form submissions and the like. PUT updates an existing resource wholesale, and DELETE removes it. There is also a frequently used method called PATCH that updates only part of a resource.

An important property here is idempotency. GET, PUT, and DELETE should be operations where "the final state is the same no matter how many times you send the same request," which is called idempotent. POST, on the other hand, adds a new resource each time you send it, so it is not idempotent. This is an important concept tied to whether a request can be safely re-sent when communication fails midway.

Endpoints and Resource Design

An endpoint is the concrete URL used to access a resource. In REST, the convention is to express endpoints as plural nouns (resource names) and to distinguish operations by method. For an API that handles users, for example, you would design it like this.

GET /users → Get the list of users
GET /users/123 → Get the user with ID 123
POST /users → Create a new user
PUT /users/123 → Update the user with ID 123
DELETE /users/123 → Delete the user with ID 123

The key point is not to put verbs like /getUser or /deleteUser into the URL. Since the method expresses "what to do," the URL plainly expresses only "which resource." This keeps the number of endpoints down and makes the API regular and predictable.

Resources can also have a hierarchy. For example, /users/123/orders means "the list of orders for the user with ID 123." When you want to break down and check such a URL structure, viewing the path and query parts separately in the URL Parser makes the design intent easier to grasp. The more complex the endpoint, the more it helps to split each element apart in the URL Parser.

How to Read Status Codes

In response to a request, the server returns the result as a three-digit HTTP status code. The leading digit conveys the rough meaning, so grasping this lets you quickly read an API's response.

2xx indicates success; typically 200 is returned when data retrieval succeeds and 201 when creation succeeds. 4xx indicates a problem on the side that sent the request: 404 means "resource not found," 401 means "authentication required or failed," and 400 means "the request format is wrong." 5xx is an internal server fault, a problem on the provider's side rather than the user's. When an error occurs, the first step is to look at this number to separate "is it my problem or the other side's problem."

Requests and Responses: JSON and Query Parameters

For exchanging data in a REST API, a lightweight data format called JSON (JavaScript Object Notation) is used in almost all cases today. Its strength is that it is readable for humans and easy for programs to handle. For a POST request that creates a user, for example, you send JSON like the following in the body.

{
  "name": "Taro Yamada",
  "email": "taro@example.com"
}

The server returns the result, also as JSON. If creation succeeds, for example, you get back a response that includes the assigned ID. When the JSON you receive is tangled and hard to read, pasting it into the JSON Formatter to fix the indentation makes the structure clear at a glance. Even single-line JSON with no line breaks becomes easy to see in its hierarchy once you format it in the JSON Formatter.

Meanwhile, for filtering and sorting when retrieving data with GET, you use query parameters. Append ? to the end of the URL and specify key=value pairs joined with &.

GET /users?role=admin&sort=created&page=2

This example means "get only page 2 of users with the admin role, ordered by creation date." When many parameters are strung together and hard to read, breaking the query part into keys and values with the aforementioned URL Parser makes checking easier.

An Overview of Authentication

Some APIs allow anyone to access them freely, but many require authentication to verify the user. Because REST is stateless, you include the authentication information in every request as a rule. The representative methods are as follows.

• API key: the simplest method, sending an issued string in a header or query.
• Bearer token (such as JWT): a method that sends a token received after login in the Authorization header. This is the mainstream today.
• OAuth 2.0: a mechanism that securely authorizes access to a third-party service's data without handing over your password. It is used for things like "Sign in with Google."

In any method, the authentication information amounts to a secret key. Writing it directly in the URL query tends to leave it in history and logs, so you normally put it in a header and always exchange it over HTTPS (encrypted communication). If authentication does not pass, you get the aforementioned 401 or 403 (forbidden).

As we have seen, a REST API is built from a small set of parts: "resource (URL)," "operation (HTTP method)," "result (status code)," and "data (JSON)." Start by formatting a familiar API's response in the JSON Formatter and breaking down its endpoint in the URL Parser, and you should get a concrete grasp of the mechanism. Observing while moving your hands is the shortcut to understanding APIs.

Please note that this article is intended to provide general information. API specifications, authentication methods, and recommended designs vary by provider and version and can change over time. When you actually use an API, always check its latest official documentation before making decisions.