What Is an API? REST, HTTP Methods, and Status Codes Explained Simply

How do client and server actually talk to each other?#

Picture sitting at a tea shop near Tidel Park in Chennai. You place an order with the waiter for a ginger tea. You do not march into the kitchen, light the stove, or boil the milk yourself. The waiter takes your exact order, delivers it to the kitchen counter, and brings your cup back.

In software, your browser or mobile phone is the client. The backend database holding millions of records is the kitchen. The API (Application Programming Interface) is that waiter.

An API defines a strict contract between two programs. It lays down clear rules: send data to this exact web address, use this specific format, and I will hand back the exact answer you need. When you book a train ticket on an aggregator app, the app does not hold Indian Railways seat data. It calls the IRCTC API, fetches real-time berth availability, and shows it on your screen.

REST (Representational State Transfer) is just an architectural style for organizing these rules over HTTP. It treats data items—like users, orders, or tickets—as 'resources' identified by unique web addresses (URLs). Instead of creating messy custom commands, REST relies on the standard plumbing that has powered the internet for decades.

Which HTTP methods do you really need to know?#

When your client talks to a REST API, it sends an HTTP method (often called an HTTP verb) alongside the URL. This verb tells the server exactly what action you want to take on that resource.

Five standard verbs handle 99 percent of day-to-day web development:

• GET: Retrieves data. Visiting a Flipkart product page sends a GET request to fetch product details. GET must never modify data on the server.
• POST: Creates brand-new data. Submitting a signup form or creating a new delivery order sends a POST request with the new details tucked inside the request body.
• PUT: Replaces an existing resource completely. If you update a profile using PUT, you send the whole profile payload, replacing whatever was there before.
• PATCH: Updates part of an existing resource. If you only want to change your UPI payment PIN or mobile number, PATCH updates just that field without touching the rest of your account.
• DELETE: Removes a resource. Clicking 'Remove item' in your shopping cart triggers a DELETE call targeting that specific cart item ID.

Here is how a standard JavaScript fetch call uses the POST method to create a new support ticket:

const createTicket = async () => {
  const response = await fetch('https://api.example.com/v1/tickets', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer token_abc123'
    },
    body: JSON.stringify({
      title: 'Payment failed but money debited',
      priority: 'high'
    })
  });
  const data = await response.json();
  return data;
};

What do these HTTP status codes actually tell you?#

Every time an API server answers your request, it sends back a three-digit HTTP status code. Think of this code as a quick signal light before you even inspect the data.

Instead of guessing, memorize the code families by their first digit:

• 2xx (Success): Everything went as planned. 200 OK means data was retrieved or updated successfully. 201 Created means a new resource was successfully added to the database.
• 3xx (Redirection): The resource moved. 301 Moved Permanently tells browsers to update their bookmarks to the new URL.
• 4xx (Client Error): You sent an invalid request. 400 Bad Request means your JSON syntax is broken or missing required fields. 401 Unauthorized means you forgot to send an authentication token. 403 Forbidden means the server knows who you are, but your role does not have permission. 404 Not Found means the requested URL or ID does not exist.
• 5xx (Server Error): Your request was fine, but the server crashed or timed out. 500 Internal Server Error means an unhandled exception took down the backend process. 502 Bad Gateway or 503 Service Unavailable usually means the upstream service is overloaded during a flash sale.

Clean APIs return accurate status codes. If a user enters the wrong password, an API should never send back a 200 OK containing an error message inside the body. It should return a 401 Unauthorized.

How do JSON payloads carry your data?#

APIs used to trade data using heavy XML files stuffed with closing tags. Today, nearly every REST API communicates using JSON (JavaScript Object Notation). It is lightweight, readable for humans, and native to every modern programming language.

JSON represents data using key-value pairs, arrays, strings, numbers, booleans, and null values. Keys must always sit inside double quotes.

Here is an example of a realistic API response payload for a food delivery order on an app like Swiggy:

{
  "order_id": "OD-98234",
  "restaurant_name": "Murugan Idli Shop",
  "total_amount_inr": 340.50,
  "is_delivered": false,
  "items": [
    {
      "item_id": 101,
      "name": "Ghee Podi Idli",
      "quantity": 2,
      "price": 140.00
    },
    {
      "item_id": 204,
      "name": "Filter Coffee",
      "quantity": 1,
      "price": 60.50
    }
  ],
  "delivery_partner": null
}

When your frontend framework fetches this response, it parses the JSON text directly into a native object. You can instantly read data.restaurant_name or iterate over the data.items array.

How can you test APIs with curl and Postman?#

Never wait for a frontend interface to be built before testing your backend routes. You can test endpoints right from your command line using curl, or with a graphical tool like Postman.

curl comes pre-installed on macOS, Linux, and modern Windows terminals. It is fast, scriptable, and ideal for quick checks.

Here is how you test a public REST API endpoint directly using curl to fetch a list of posts, followed by a POST request to submit data:

1. Send a GET request to inspect headers and data
curl -i https://jsonplaceholder.typicode.com/posts/1

# 2. Send a POST request with a JSON payload and headers
curl -X POST https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -d '{"title": "My first API post", "body": "Testing REST endpoints", "userId": 1}'

If you prefer a visual interface, Postman lets you paste in the URL, pick the HTTP verb from a dropdown, add authentication headers, paste your JSON body, and hit 'Send'. You get the full response, headers, timing metrics, and status code formatted clearly on one screen.

Which common mistakes get developers into trouble?#

Junior engineers often run into the same handful of API design traps:

• Putting verbs in your URLs: In REST, URLs should name resources (nouns), not actions. Use POST /api/v1/orders, not POST /api/v1/createOrder. The HTTP method already describes the action.
• Returning 200 OK for errors: Never return an HTTP 200 with a body like {"success": false, "error": "User not found"}. That breaks standard HTTP caching and confuses frontend interceptors. Use 404 Not Found instead.
• Confusing 401 and 403: Use 401 Unauthorized when the client provided no credentials or invalid tokens. Use 403 Forbidden when the client is logged in, but lacks permission to view that resource.
• Sending request bodies with GET: While technically allowed by some HTTP specs, many proxies, firewalls, and CDNs strip bodies from GET calls. Use URL query parameters for GET requests instead.

Where does this come up in Indian tech interviews?#

Whether you are interviewing for a graduate trainee slot at TCS or Infosys, or targeting product firms like Zoho, Swiggy, and Razorpay, API fundamentals show up in round one. Interviewers frequently ask candidates to explain the difference between PUT and PATCH, or what status code an authentication failure should return. They will look at whether you understand idempotency—why repeating a GET or PUT multiple times produces the same server state, while repeating a POST creates duplicate records. Nailing these core fundamentals proves you understand real-world web architecture, not just framework syntax.

What is your weekend practice task?#

Open your computer terminal right now and make your first real API call. Use curl to hit the free JSONPlaceholder testing service. Run a GET request to view post number 10, check the status code, and then try sending a POST request with your name as the author. Once you see a 201 Created response return in your console, you will understand how every web application on your phone actually functions under the hood.