APIs beginner to advanced: GET vs POST, JSON, and status codes explained
A beginner's guide to APIs: how requests and responses work, GET vs POST, JSON, and status codes, plus interview questions and a small AWS practice project.
Series: New To AWS Beginners Guide (11 articles)
- …
- 6APIs beginner to advanced: GET vs POST, JSON, and status codes explained This article
New to AWS: API Fundamentals, Part 1
An API (application programming interface) is a set of rules for how one piece of software asks another for data or actions. With a web API, a client sends a request and a server sends back a response. Developers call that exchange the request-response cycle.
The request-response cycle was the first concept I learned as a developer. It showed me what happens between clicking a button and seeing the screen change.
This beginner guide follows two everyday actions: opening a product page and placing an order. By the end, you'll be able to point at a method, path, request body, status code, and JSON response, and say which part of the app did the work. It also sets you up for the rest of this series on Amazon API Gateway.
The examples use a made-up headphone store inspired by shopping on Amazon.com. I invented the routes, payloads, and database design for teaching, so they don't describe how Amazon.com works.
What is the request-response cycle?
In the request-response cycle, a client asks for something and a server sends a result back.
You click a pair of headphones, and the page fills in with a name, photos, a price, and reviews. In our simplified store, four things happen:
- The browser asks for the product's information.
- The backend works out which product you want and reads its record from a database.
- The backend sends back a response with the product data.
- The frontend uses that data to update the page.
The client is the software making the request. In this case that's your browser, but a mobile app or another backend service can be a client too.
The server is the software that receives and handles the request. Before it responds, it may check the input, run application logic, and call other services. The frontend is the interface you interact with, and the backend is the code and data behind it.
The database holds the product records. Your browser talks to our backend. It never queries the product database itself.
A real product page fires off many requests, including separate ones for images and reviews, and a backend might read from a cache instead of the database. Following one request keeps each part's job easy to see.
What does an API define?
An API defines which operations you can call, what information you send, and what results you get back. Developers often call this agreement the API contract.
Products and orders are resources, the things our API lets clients work with. For our store, the contract might look like this:
| Operation | Request | Successful result in this example |
|---|---|---|
| View a product | GET /products/123 | 200 OK with product data |
| Place an order | POST /orders with order details | 201 Created with an order ID |
The three-digit numbers are status codes, a quick signal of how the request went. I cover them below.
The store's buttons help a person use these operations, but the server has to enforce the rules. Hiding a price-editing button won't stop someone from building their own request, so our backend calculates the order price from product data it trusts.
The API and the database are separate things. The API exposes a chosen set of operations, and the database stores the information those operations need.
What are HTTP methods, paths, and routes?
The method says what operation you want. The path says what the request is about. A route pairs a method with a path or path pattern.
HTTP (Hypertext Transfer Protocol) sets the format for web requests and responses and how they're exchanged. HTTPS sends HTTP over an encrypted connection. These are the fields that matter in our product request:
1
2
3
GET /products/123 HTTP/1.1
Host: api.example.test
Accept: application/jsonThis example request goes to a fictional host. It isn't a live endpoint.
GETis the method. It asks for data. Don't use it to place an order or make any other business change./products/123is the path. In our design, it points to product123.123is a path parameter value. Our router could define the patternGET /products/{productId}and pull out123asproductId.Accept: application/jsonis a header. It tells the server the client would like JSON back.
Headers carry metadata about a message. The body is the data the message carries. This GET request has no body, because the product ID is already in the path.
The method matters as much as the path. If our app implemented both
GET /orders and POST /orders, they'd be two different operations.What is JSON, and how does product data reach the page?
JSON (JavaScript Object Notation) is a text format for sending structured data. Despite the name, you can use it from almost any programming language.
Our response body could hold this JSON object:
1
2
3
4
5
6
7
{
"productId": "123",
"name": "Everyday Headphones",
"price": 79.99,
"currency": "USD",
"inStock": true
}An object groups names and values inside curly braces. In this one,
"name" is a property name (also called a key), and "Everyday Headphones" is its value. Text values go in quotes. Numbers and true or false don't. JSON can also hold arrays, which are lists, and objects nested inside other objects.The response's
Content-Type: application/json header tells the browser what format the body is in. The frontend parses the JSON, turning the text into data its code can use, and then shows the name and price.JSON has nothing to do with how the page looks. The frontend decides the layout, colors, and buttons. A JSON response can include an image's address, and the browser then fetches the image with its own request.
APIs can also return HTML, images, other formats, or an empty body. I picked JSON for this example.
What changes when you send a POST request?
POST sends data for the server to process. Creating a resource is a common use, but POST can do other jobs too.
In our store, clicking Place your order sends
POST /orders. Its Content-Type header is application/json, and the request body contains:1
2
3
4
5
6
7
8
9
10
{
"productId": "123",
"quantity": 1,
"color": "black",
"shippingAddress": {
"line1": "10 Example Street",
"city": "Example City",
"country": "US"
}
}I made up that address. Stick to test data in the learning project too.
This time the backend has work to do before it replies:
- Check the product ID, quantity, color, and other required fields.
- Look up the product and calculate the price on the server.
- Create an order ID and save an order record in the Orders table.
- Send back the API response.
The request never tells the server what price to charge. The price the browser shows you isn't the price the server trusts for the purchase.
Once the save succeeds, our implementation returns
201 Created with a JSON body like this:1
2
3
4
5
6
{
"orderId": "ORD-1001",
"status": "received",
"total": 79.99,
"currency": "USD"
}The server created the order. That doesn't mean the headphones have shipped or that the later business steps are done. A real store would handle payment and fulfillment as separate steps.
GET vs POST: the beginner's summary
| Question | GET in our store | POST in our store |
|---|---|---|
| What do we want? | Retrieve product information | Create an order |
| Where is the key input? | Product ID in the path | Order details in the JSON body |
| What does the backend do? | Looks up the product | Validates details and saves an order |
| What comes back? | 200 plus product data | 201 plus an order ID |
The method itself doesn't do any of that work. Your backend code has to implement it. The backend can also reject a request with perfectly valid JSON, like an order for a quantity of
-1.What are HTTP status codes?
A status code is a three-digit number that sums up the result of an HTTP request. Read it alongside the response body to get the full picture.
The first digit tells you the broad category:
1xxis informational.2xxmeans success.3xxis about redirects.4xxmeans the server can't fulfill the request as you sent it.5xxmeans something failed on the server.
These are the codes that come up in our store:
| Code | Meaning | Example |
|---|---|---|
200 OK | The request succeeded | The backend returns the requested product |
201 Created | The request created a resource | The backend creates an order |
400 Bad Request | The server rejects a problem with the request | Our app rejects quantity -1 |
404 Not Found | The requested resource wasn't found, or its existence isn't disclosed | Our app can't return product 999 |
500 Internal Server Error | The server encountered an unexpected problem | An unhandled backend error prevents completion |
These rows describe our API's design. Other APIs might return a
400 from a different component, or answer a POST with something other than 201.Don't mix up the HTTP status
201 with the JSON field "status": "received". The 201 reports how the HTTP request went, and "received" is the order's state inside the application.API terminology: a quick reference
| Term | Plain-English meaning | Store example |
|---|---|---|
| API contract | The agreed operations, inputs, and outputs | How to fetch a product or place an order |
| Resource | Something the API lets clients work with | A product or an order |
| Client | Software making the request | The browser |
| Server | Software handling the request | Our backend application |
| Endpoint | An address clients call to reach an API operation | The API's address plus /products/123 |
| Method | The requested HTTP operation | GET or POST |
| Path | The part of the address identifying the target | /products/123 |
| Route | A method and path pattern matched by the backend | GET /products/{productId} |
| Header | Metadata about a message | Content-Type: application/json |
| Body / payload | Data carried in a message | Order details or returned product data |
| JSON | A text format for structured data | Product names, numbers, and availability |
| Status code | A short signal about the HTTP result | 200, 201, or 404 |
| Database record | Stored application information | The saved order with ID ORD-1001 |
How do you see API requests in your browser?
Open your browser's developer tools and select the Network tab. On an app you control, do something with fake data, then click one of the requests.
Find its method, URL, status, and response. For a POST request, check the payload and the
Content-Type header too.Filtering to Fetch/XHR makes API calls easier to spot. Page navigations can return HTML, so don't expect JSON in every row of the Network tab. Look for the response that carried the data you care about.
Before you change any code, ask yourself two questions. What did the frontend send, and what did the backend return?
Beginner API interview questions and sample answers
1. What is an API?
An API defines how one piece of software asks another for data or actions. In our store, the API describes how to request a product and which details you need to submit an order.
2. Walk me through what happens when I open a product page.
The browser sends a request such as
GET /products/123. The backend finds the product, gets its data, and sends a response. The frontend reads the response and updates the page. Real pages often send several requests.3. What is the difference between GET and POST?
GET retrieves a representation of a resource. POST sends data for the server to process. Our store uses GET to read product details and POST to create an order, though POST can do more than create things.
4. What is the difference between a path parameter and a request body?
In
/products/123, the 123 in the path identifies the product. A request body carries extra data, such as the quantity, color, and address in our order. The API contract decides where each input goes.5. Is JSON an API or a programming language?
It's neither. JSON is a data format an API can use. Our JSON object holds product information, and the API contract explains how to request it. Code in many languages can write and read JSON.
6. What is the difference between 200 and 201?
Both mean the HTTP request succeeded.
200 is the general success code. 201 means the request created one or more resources. Our product lookup returns 200, and a successful new order returns 201.7. If the browser sends a lower price, should the server accept it?
No. Our backend calculates the price from product information it trusts and the rules that apply. A client can send edited values even when the website has no button for changing the price.
8. If the app never receives a response, did the order fail?
Not necessarily. The backend may have saved the order and then lost the response on the way back. Retrying could create a second order unless the app protects against duplicates. A missing confirmation doesn't prove the server did nothing.
Try answering each question out loud before you read the sample answer. Use the request, the response, and the stored record to explain your reasoning.
Practice on AWS: build a small API with API Gateway, Lambda, and DynamoDB
Build ShopRequestLab, a practice app with two actions: view a fake product and place a fake order. Keep the frontend on your laptop while you learn the backend.
Use Amazon API Gateway as the front door for your API, AWS Lambda for the product and order logic, and Amazon DynamoDB for the Products and Orders tables. API Gateway receives each request and passes it to Lambda. Your Lambda code checks the input and reads or writes the stored records.
The new AWS signup experience supports all three services. Use your project's assigned Region, and check its plan and the credits you have. Eligible credits can cover charges for this practice app. Start with my guide to the new AWS signup experience .
Then connect your coding assistant with my Agent Toolkit for AWS setup guide . The toolkit helps your assistant build and inspect AWS resources. It plays no part when a customer places an order.
Give your assistant this small challenge:
1
2
3
4
5
6
7
8
9
Help me build ShopRequestLab and explain each step.
Use Agent Toolkit for AWS to confirm my project and assigned Region.
Show the resources, permissions, and expected usage before deployment.
Build GET /products/{productId} and POST /orders using an HTTP API,
Lambda, and DynamoDB. Use fake data and keep the frontend local.
Return JSON, validate quantity and color, and calculate price on the backend.
Demonstrate 200, 201, a missing-product 404, and our invalid-quantity 400.
Configure CORS for the actual local frontend origin and explain what it does.
Stay on my current plan and provide a cleanup inventory.CORS (cross-origin resource sharing) tells a browser which websites can read your API's responses. It doesn't check who the user is. Stick to fake data while your learning API is public, and add authentication and per-user access controls before you handle real orders.
You're done when you can find a request, read its JSON response, locate the saved fake order, and explain each step. In part two, I'll take a closer look at what API Gateway does.
Series: New To AWS Beginners Guide (11 articles)
- …
- 6APIs beginner to advanced: GET vs POST, JSON, and status codes explained This article
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article