Anatomy of a REST API Request Explained

Every API request follows a predictable structure.

Whether you're testing APIs with Postman, sending requests using cURL, or integrating third-party services into an application, understanding the anatomy of a REST API request helps you troubleshoot issues faster and build more reliable software.

A REST API request contains several components that tell the server what action to perform, which resource to access, what data is being sent, and how the response should be returned.

If you're new to REST APIs, start with this guide on What Is a REST API?.

What Is the Anatomy of a REST API Request?

The anatomy of a REST API request refers to all the parts that make up a complete HTTP request sent from a client to a server.

A typical REST API request consists of:

• HTTP method
• Endpoint (URI)
• Request headers
• Query parameters (optional)
• Request body (optional)

Each component serves a specific purpose and helps the server understand exactly what the client wants.

Components of a REST API Request

HTTP Method (Verb)

The HTTP method defines the action you want to perform on a resource.

The most common methods used in REST APIs are:

• GET – Retrieve data from a server
• POST – Create a new resource
• PUT – Replace an existing resource
• PATCH – Partially update a resource
• DELETE – Remove a resource

For detailed explanations of each method, see:

• GET Method in REST API
• POST Method in REST API
• PUT Method in REST API
• PATCH Method in REST API
• DELETE Method in REST API
• HTTP Methods in REST API

Developer Insight

In production systems, GET and POST requests typically account for most API traffic.

A common mistake is confusing PUT and PATCH requests. PUT usually replaces the entire resource representation, while PATCH updates only the fields specified in the request.

Endpoint (URI)

The endpoint identifies the resource you want to access.

An endpoint is usually a URI that includes:

• Protocol
• Domain name
• API path
• Resource identifier

Example:

https://api.example.com/users/12345

In this example:

• https is the protocol
• api.example.com is the host
• /users is the resource collection
• 12345 identifies a specific user

If you're unsure about the differences between URLs, URIs, and URNs, read URL vs URI vs URN.

Headers

Headers provide additional information about the request.

Common request headers include:

• Authorization
• Content-Type
• Accept
• User-Agent

Example:

Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
Accept: application/json

Authorization Header

The Authorization header is used to verify that the client has permission to access the requested resource.

Authentication mechanisms commonly used in REST APIs include:

• API Keys
• OAuth 2.0
• JWT (JSON Web Tokens)

Learn more in REST API Authorization and Authentication.

Content-Type Header

The Content-Type header tells the server how to interpret the request body.

Common values include:

Content-Type: application/json

Content-Type: application/xml

JSON is the most widely used format for modern REST APIs.

You can learn more about JSON from the official JSON Website.

Common API Error

One of the most common causes of failed API requests is a missing or incorrect Content-Type header.

If the server expects JSON but receives a different format, it may reject the request with a 400 Bad Request or 415 Unsupported Media Type response.

Query Parameters

Query parameters provide additional information to filter, sort, or customize a request.

They appear after a question mark (?) in the URL.

Example:

https://api.example.com/products?category=electronics&price=under500

In this example:

• category=electronics filters products by category
• price=under500 filters products by price range

Common use cases include:

• Filtering results
• Sorting data
• Pagination
• Searching resources

Example:

https://api.example.com/users?page=2&limit=20

Request Body

The request body contains data sent to the server.

It is commonly used with:

• POST requests
• PUT requests
• PATCH requests

Most modern APIs use JSON for request bodies.

Example:

{
  "name": "John Doe",
  "email": "johndoe@example.com"
}

Pro Tip

When debugging API requests, the issue is often caused by:

• Invalid JSON syntax
• Missing authentication credentials
• Incorrect headers
• Typographical errors in endpoint paths

Checking these items first can save a significant amount of troubleshooting time.

REST API Request Example

The following example creates a new user using a POST request.

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "John Doe",
  "email": "johndoe@example.com"
}

Here's what each component does:

• POST specifies the action
• /users identifies the target resource
• Host identifies the server
• Content-Type tells the server the body contains JSON
• The request body contains the user data

What Happens After the Request Is Sent?

After receiving the request, the server processes it and returns an HTTP response.

A response typically contains:

• Status code
• Response headers
• Response body

Example:

HTTP/1.1 201 Created
Location: /users/101

In this example, the server successfully created a new resource and returned the 201 Created status code.

To understand the full request-response lifecycle, see REST API Request and Response Pair.

HTTP Status Codes

Status codes indicate the outcome of the request.

Some common examples include:

• 200 OK – Request succeeded
• 201 Created – Resource created successfully
• 400 Bad Request – Invalid request
• 401 Unauthorized – Authentication required
• 403 Forbidden – Access denied
• 404 Not Found – Resource does not exist
• 500 Internal Server Error – Server-side failure

For a detailed breakdown, read:

• HTTP Status Message in REST API

Response Headers

Response headers contain metadata about the response.

Examples include:

• Content-Type
• Cache-Control
• Content-Length
• ETag

Learn more in Response Header in REST API.

Common Mistakes When Making REST API Requests

Developers frequently encounter the following issues:

Using the Wrong HTTP Method

Attempting to create data using GET instead of POST can result in unexpected errors.

Always verify the API documentation before sending requests.

Missing Authentication Information

Many APIs require API keys, OAuth tokens, or JWTs.

Without valid credentials, the server will usually return a 401 Unauthorized response.

Invalid JSON Formatting

A missing comma, bracket, or quotation mark can cause the request body to fail validation.

Use tools such as:

• Postman
• Insomnia
• cURL

to validate requests during development.

Incorrect Endpoint Path

Even a small typo in a URI can result in a 404 Not Found error.

Always verify endpoint names, resource IDs, and path parameters.

Frequently Asked Questions

How do I make a REST API request?

You can make REST API requests using:

• Postman
• Insomnia
• cURL
• Programming languages such as Python, Java, Go, JavaScript, and C#

These tools send HTTP requests to API endpoints and display the responses returned by the server.

How do I know if my REST API request was successful?

Check the HTTP status code returned in the response.

Codes in the 2xx range generally indicate success.

For example:

• 200 OK
• 201 Created
• 204 No Content

Are query parameters the same as request body parameters?

No.

Query parameters are included in the URL and are commonly used for filtering, sorting, and pagination.

Request body parameters are sent inside the request payload and are typically used when creating or updating resources.

Is a request body required for every REST API request?

No.

GET and DELETE requests typically do not require a request body.

POST, PUT, and PATCH requests often include one because they send data to the server.

How is REST related to HTTP?

REST is an architectural style that commonly uses HTTP as its communication protocol.

Learn more in How REST API Is Related to HTTP.

Related REST API Articles

To continue learning REST APIs, explore these guides:

• What Is a REST API?
• Resource in REST API
• Discovery in REST API
• REST API Authorization and Authentication
• REST API Request and Response Pair
• Tools to See REST API in Action
• Constraints of REST API