HTTP Methods in REST API: GET, POST, PUT, PATCH, DELETE

HTTP methods are the verbs of your API, telling servers what action to perform on a resource. When you use them correctly, you create a clear contract that enables faster developer integration, better tooling support, and cleaner SDK generation.

This guide covers the five core HTTP methods (GET, POST, PUT, PATCH, DELETE), their safety and idempotency properties, and how your method choices directly impact the developer experience through SDK generation and automated tooling.

Why HTTP methods matter to API providers

HTTP methods are the verbs of your API, telling servers what action to perform on a resource. The five most common methods are GET, POST, PUT, PATCH, and DELETE, which correspond to reading, creating, replacing, updating, and deleting resources. Choosing the right method for each endpoint is the foundation of a predictable, reliable REST API that is easy for both humans and machines to use.

When you use HTTP methods correctly, you create a clear contract for your API's consumers. This predictability allows developers to integrate faster and enables automated tooling, like SDK generators and documentation platforms, to work seamlessly. It also improves caching, simplifies debugging, and makes it easier to evolve your API without breaking client integrations.

Five core HTTP methods

At their core, HTTP methods map directly to the create, read, update, and delete (CRUD) operations that are fundamental to most applications. As an API provider, your responsibility is to ensure each endpoint uses the correct method, responds with the right status codes, and maintains a consistent structure. This consistency is what allows developers to build reliable integrations on top of your service.

Here is a quick breakdown of the five primary methods and their properties.

Use GET for retrieval

The GET method is used to request a representation of a specified resource. Because GET requests are only for retrieving data, they should never modify the state of the resource on the server. This property makes them safe and cacheable by browsers and intermediary proxies.

A GET request should not have a request body. Any parameters needed to filter or specify the resource should be sent as URL query parameters, like /users?role=admin. Well-designed APIs use GET for list endpoints, which can be enhanced with pagination helpers in a client SDK to make fetching large datasets trivial.

Use POST for creation

Use the POST method to submit an entity to the specified resource, often causing a change in state or side effects on the server. The most common use case is to create a new resource, such as creating a new user or posting a message. A successful POST request to a creation endpoint should return an HTTP 201 Created status code along with a Location header that contains the URL of the newly created resource.

Because POST requests can have different effects on each call, they are not idempotent. For example, calling POST /users twice would create two distinct users. This is why a well-designed SDK will map this method to an intuitive function like client.users.create().

Use PUT for replacement

The PUT method replaces all current representations of the target resource with the request payload. It is used for complete updates. If the resource does not exist, PUT can create it at the specified URI.

PUT is idempotent, meaning that making the same PUT request multiple times will have the same effect as making it once. This makes it a reliable choice for operations that need to be retry-safe. For example, if a network error occurs during a PUT request, a client can safely send the request again without worrying about creating duplicate resources or causing unintended side effects.

Use PATCH for modification

When you only need to apply a partial update to a resource, the PATCH method is the right tool. Unlike PUT, which replaces the entire resource, PATCH applies a set of changes described in the request body. For example, you could use PATCH to update a user's email address without sending their entire user profile.

The exact format for a PATCH request, such as JSON Merge Patch or JSON Patch, should be specified by the API. Because the outcome of a PATCH can depend on the current state of the resource, it is not considered idempotent.

Use DELETE for removal

The DELETE method removes the specified resource. Like PUT, DELETE is idempotent because calling it multiple times on the same resource has the same effect as calling it once. The resource is deleted on the first call, and subsequent calls will typically return a 404 Not Found, confirming the resource is gone.

A successful DELETE request usually returns an HTTP 204 No Content response with no response body. This signals to the client that the action was successful and there is nothing further to display.

Safety and idempotency principles

Understanding safety and idempotency is crucial for designing a robust and predictable API. These two concepts define how clients can interact with your endpoints, especially in the face of network failures.

• Safety: A method is safe if it does not alter the state of the server. GET and HEAD are safe methods because they are strictly for retrieval. Clients, proxies, and search crawlers can make safe requests without any fear of causing side effects.

• Idempotency: A method is idempotent if making multiple identical requests has the same effect as making a single request. PUT and DELETE are idempotent. This property is critical because it allows clients to safely retry requests that may have failed due to network issues.

These are not just theoretical principles. Smart clients and SDKs use these properties to build in powerful features like automatic retries with exponential backoff, providing a more resilient developer experience without any extra work from the consumer.

Status code patterns by method

Returning consistent and correct HTTP status codes is just as important as choosing the right method. Status codes provide immediate feedback to the client about the outcome of their request. A well-designed API uses a predictable pattern of status codes for each method.

Here are some common patterns:

• GET: Returns 200 OK with the resource, or 404 Not Found if it doesn't exist.

• POST: Returns 201 Created with a Location header pointing to the new resource, or 400 Bad Request if the input was invalid.

• PUT/PATCH: Returns 200 OK if an existing resource was updated, or 204 No Content. It can also return 201 Created if the request created a new resource.

• DELETE: Returns 204 No Content on success, or 404 Not Found if the resource was already gone.

When your API consistently follows these patterns, it enables SDK generation to provide strongly-typed error classes. This allows developers to write clean error-handling logic, like catching a specific NotFoundError, instead of manually parsing generic HTTP error responses.

Method choice impact on SDK generation

Your choices as an API provider have a direct impact on the developer experience of your users. A well-structured REST API translates directly into a clean, intuitive, and ergonomic SDK. The HTTP methods you choose are a primary driver of that experience.

Map methods to intuitive functions

A logical API structure allows SDK generators to create methods that feel hand-crafted. The mapping is straightforward and predictable for developers.

• GET /users becomes client.users.list()

• POST /users becomes client.users.create()

• GET /users/{id} becomes client.users.retrieve(id)

• PATCH /users/{id} becomes client.users.update(id, {...})

• DELETE /users/{id} becomes client.users.delete(id)

This clear mapping removes ambiguity and makes your API a pleasure to use, reinforcing the principle that your API isn't finished until the SDK ships.

Enable automatic retries through idempotency

When you correctly mark methods like PUT and DELETE as idempotent, you signal to client libraries that they can be safely retried. A robust SDK will use this signal to automatically handle transient network failures. This built-in resilience saves your users from writing complex and error-prone retry logic themselves.

Simplify LLM tools with clear verbs

In the age of AI, your API is increasingly consumed by language models, not just humans. The Model Context Protocol (MCP) allows LLMs to interact with APIs through "tools," and generating MCP servers from OpenAPI specs makes this integration seamless.

When an API endpoint like POST /products is exposed as an MCP tool, it becomes an intuitive create_product tool. The process of converting complex OpenAPI specs to MCP servers ensures these tools maintain clarity and functionality.

Additional HTTP methods

While the five core methods cover most use cases, a few others serve specific purposes. Using them correctly can add precision to your API, but they are needed less frequently.

Use HEAD for metadata

The HEAD method is identical to GET, but it does not return a response body. It's used to retrieve the headers that would be returned if a GET request were made. This is useful for checking if a resource exists or for getting its metadata, like its Content-Length or ETag, without downloading the entire resource.

Use OPTIONS for capability discovery

The OPTIONS method is used to describe the communication options for the target resource. A client can use an OPTIONS request to determine which HTTP methods a server supports for a given URL. It is also used in Cross-Origin Resource Sharing (CORS) as part of a "pre-flight" request to ensure the actual request is safe to send. When you create OpenAPI specs, these OPTIONS methods are often included to fully describe your API's capabilities.

Avoid TRACE and CONNECT in production

The TRACE and CONNECT methods are typically used for debugging and proxying. TRACE echoes the received request back to the client, while CONNECT establishes a tunnel to the server identified by the target resource. Due to security concerns, they are often disabled on production servers, and SDK generators will typically ignore them.

Common mistakes to avoid

Building a great API also means avoiding common pitfalls. These mistakes can lead to a confusing developer experience and brittle client integrations.

Overload POST for every action

A frequent anti-pattern is using POST for any action that modifies data, including updates and deletions. This breaks the clear contract of REST and forces developers to learn the specifics of your API rather than relying on web standards. It also results in poorly designed SDKs with ambiguous method names like client.perform_user_update() instead of a clean client.users.update(). When you integrate SDK snippets with your API docs, these confusing method names become even more apparent to developers trying to understand your API.

Break idempotency with unsafe updates

If a PUT or DELETE request has side effects that change with each call, it is no longer idempotent. For example, if DELETE /cart/items decremented a stock counter every time it was called, a retried request could cause the stock to be double-counted. This can lead to serious data integrity issues when clients retry failed requests.

Return inconsistent status codes

Returning a 200 OK for a failed request or using custom success codes confuses clients. Standard HTTP status codes are a universal language. Deviating from them breaks automated tooling and forces developers to write custom logic to parse your specific responses, defeating the purpose of a standardized protocol.

Frequently asked questions about HTTP methods in REST APIs

Should my API support all HTTP methods?

No, an API should only implement the methods that are relevant to its resources. Most APIs are well-served by the core five methods (GET, POST, PUT/PATCH, DELETE), with others added only when a specific need like caching (HEAD) or CORS (OPTIONS) arises.

Can I use custom HTTP methods?

While technically possible, using custom HTTP methods is strongly discouraged. They are not understood by standard tooling, caches, or intermediaries, which breaks interoperability and negates many of the benefits of using HTTP.

How do HTTP methods work with API versioning?

HTTP methods are independent of API versioning. The semantics of GET, POST, and other methods should remain consistent across all versions of your API. Versioning is typically handled through the URL path (e.g., /v2/users) or custom request headers.

What is the difference between PUT and POST when creating resources?

The key difference lies in idempotency and who controls the resource URL. Use POST when the server assigns the URL for the new resource. Use PUT when the client specifies the exact URL where the resource should be created or updated.

Do I need idempotency keys for POST requests?

For critical operations where duplicate requests are unacceptable, such as processing a payment, using an idempotency key with POST is a best practice. Robust SDKs can automatically generate and send these keys to ensure each operation is processed only once.

Ready to provide a first-class developer experience? Get started for free and generate high-quality, idiomatic SDKs from your API spec in minutes.