API methods: a beginner-friendly guide for developers
Not sure when to use GET, POST, PUT, or DELETE? Learn all HTTP methods, their purposes, and how to use them correctly in RESTful APIs.
API methods: a beginner-friendly guide for developers
Have you ever wondered whether the endpoint for resending an SMS notification should be a POST or a GET? You might think, "Hey, it doesn't accept any request body, so it must be a GET request." Well, hold that thought because you would be wrong.
That's exactly what this article is about.
With around 30 different API methods listed by IANA, it can feel like trying to choose between a spade and a shove l— both can dig, but it doesn't mean they're interchangeable. This guide will explore various REST methods and API request methods, helping you understand their proper use cases and api functionality.
Throughout this guide, I'll break down the most common REST API methods you're likely to encounter in your day-to-day application development.
We'll cover the essential "get post put delete" operations and other http request types, unpack important concepts like idempotency, safety, and cacheability in API methods, and explore different types of api calls.
What are API methods?
HTTP methods, often referred to as API methods or REST methods, are a set of request methods that indicate the desired action to be performed on a resource in the context of client-server communication.
These methods are fundamental to understanding what is an api method and how it functions.
Whenever we send an HTTP request, a method must be specified to determine the api functionality.
Based on the method chosen, the server is able to determine the appropriate course of action and respond accordingly, often in hypermedia formats such as JSON or XML. This request-response model forms the backbone of API interactions.
Key characteristics of API methods
When discussing API methods and their functions, there are three important concepts to keep in mind: safety, idempotency, and cacheability. These characteristics are crucial for understanding the behavior of different http request types.
Safe Methods: Safe methods are those that do not modify server resources. They're designed to allow clients to interact with resources without risking alterations or side effects.
Idempotent Methods: Idempotent methods are those that can be called multiple times with the same effect as the first call. This characteristic ensures that clients can safely repeat N > 0 identical requests.
Cacheable Methods: Cacheable methods allow responses to be stored and reused for future requests, which can significantly improve API performance.
Overview of API request types
As of 2025, the Internet Assigned Numbers Authority (IANA) lists 30 HTTP methods.
However, only 9 of these methods are explicitly defined by the HTTP protocol in RFC 9110. These form the core of RESTful APIs and are essential for understanding different types of api calls.
The remaining API request types have been specified in other protocols, such as WebDAV and its siblings, CalDAV and CardDAV.
This guide will focus solely on the REST API methods that are most commonly used in RESTful applications, including the fundamental "get post put delete" operations.
GET Method
Use case: Data retrieval without any side effects, a common operation in RESTful APIs.
The GET method stands out as one of the most frequently used API request types. Its primary purpose is to retrieve data of a target resource from a server. It is both idempotent, safe, and cacheable, making it a cornerstone of API functionality.
For instance, consider the Pieces REST API. To retrieve all downloadable AI models that can be displayed in the Pieces for Desktop app, we expose an endpoint at /models dedicated to fetching this resource.
With Pieces installed on my local machine, I can easily query this API endpoint on my local server at port 39301 like this:
Once I send this request, the server will respond back with all the downloadable AI models in a handy JSON format, which looks something like this:
POST Method
Use case: Creating new resources or submitting data that needs to change the current state. It can also be used to trigger side effects, such as sending emails or adding messages to a queue.
The POST method is used to push data to the server, primarily for the purpose of data creation. It can also be used to trigger side effects on the server or an external system, making it a versatile method for various API functions.
For example, you can use a POST request to trigger resending a verification email or perform other CRUD operations. You wouldn't use a GET request here even if you don't pass a body content because it still triggers a side effect.
Also, it's good to note that POST requests are neither idempotent nor safe. But they are cacheable. Weird right? If you explicitly indicate freshness (using cache headers) and set a Content-Location header, the response will be cached.
Now, just because you can, doesn't mean you should. Unless you want to debug weird bugs down the line.
PUT Method
Use case: Updating or replacing an existing resource entirely, a common operation in RESTful APIs.
The PUT method is used to replace a known resource URI with a newly updated resource. It is also used for data updating where the resource ID is chosen by the client, making it an essential part of CRUD operations in RESTful APIs.
A typical scenario I've come across for using the PUT method is uploading a file to be stored in a blob storage such as S3 or updating a profile picture.
It's good to note PUT is neither a safe nor cacheable operation, in that it modifies (or creates) state on the server, but it is idempotent.
For instance, if you repeatedly upload a file, the existing object will be replaced each time.
DELETE Method
Use case: Removing resources from the server or database, completing the set of CRUD operations in RESTful APIs.
This method is as straightforward as the name implies; it is used for data deletion and is a crucial part of CRUD operations in API functionality.
The DELETE method requests that the origin server remove the association between the target resource and its current functionality.
In terms of characteristics, DELETE is neither safe nor cacheable, but is considered idempotent. You might wonder, "How is that possible because subsequent retries will throw error?"
Well, think about it, regardless of how many times you send a DELETE request for the same resource, the outcome remains the same.
Let me demonstrate that still using Pieces REST API. Searching through the docs, I found an endpoint to delete custom models added. If I go ahead and delete a custom model I added with the model ID 0e4dcc36-528e-4951-9e08-49e9aaae203c:
As expected, I'll get a response of 204 status code
Then, if I decide to repeat the same request, I'd get a 404 (Not Found) response. But frankly, I don't care; the model is still gone, and nothing changes in the end.
PATCH Method
Use case: Making partial updates to an existing resource without modifying the entire content, enhancing the flexibility of CRUD operations in API functionality.
Sometimes, sending an entire resource back and forth with a PUT request just doesn't make sense, especially when I'm only looking to make a small change. It feels almost like I'm wasting precious bandwidth IMO. That's precisely where the PATCH method steps in.
Introduced as part of RFC 5789, the PATCH method solves applying partial modifications to a resource rather than replacing it entirely. This makes it a much more efficient option compared to PUT when I only need to update specific attributes without overhauling the whole resource.
PATCH is not a safe operation since it modifies the resource state on the server. Additionally, It's also not inherently idempotent, but it can be in certain scenarios, such as when updating to a fixed value.
OPTIONS Method
Use case: Discovering the communication options available for a specific endpoint, crucial for understanding API functionality and available http request types.
The OPTIONS method is designed to retrieve the communication options available for a specified resource. Essentially, when you send an OPTIONS request, you're asking the server which HTTP methods and headers are supported for that particular endpoint or resource.
One of its major use cases as you might already know is for cross-origin resource sharing (CORS). It allows browsers to determine which external resources are permitted. For example, here's what an OPTIONS response might look like when you hit a cross-origin endpoint:
The OPTIONS method is considered a safe and idempotent method. However, it isn't cacheable.
HEAD Method
Use case: Fetching metadata without transferring the entire content, useful for checking resource availability in RESTful APIs.
The HEAD method is a handy tool for retrieving the metadata of a specified resource in the form of headers without downloading the entire content.
It's almost identical to the GET method, but with one significant difference: the server responds only with the headers only.
As mentioned earlier, the HEAD method closely mirrors GET requests, so it maintains the qualities of being idempotent, safe, and cacheable.
CONNECT Method
Use case: Creating secure HTTPS connections over proxy servers, an important aspect of API security and authentication.
Do you know those options in your browser settings that let you configure a proxy to route all your requests? That's where the CONNECT method comes into play. Essentially, the CONNECT method is used to establish a secure network connection (HTTPS) through a proxy server.
Upon receiving a CONNECT request, the proxy server works to set up a TCP connection to the origin, which is the server hosting the original content.
Typically, you wouldn't need to directly interact with CONNECT method in your REST service, as it is handled automatically by reverse proxies like Nginx or Caddy.
When it comes to the characteristics of the CONNECT method, it does not qualify as idempotent, safe, or cacheable.
TRACE Method
Use case: Troubleshooting and diagnostic testing of endpoint paths in RESTful APIs.
The TRACE HTTP method performs a message loop-back test along the path to the target resource. When a server receives a TRACE request, it processes the requests and echoes back all the information it received, including all headers and body content.
I've found this method to be quite useful for debugging, especially when I want to identify any changes made by intermediaries like proxies or gateways that might alter the request during its journey.
The TRACE method is idempotent and safe, and it is also not cacheable.
Safety, idempotency, and cacheable methods
Here's is a quick-reference table comparing API request types and their categorization in terms of safety, cacheability, and idempotency.
Method | Safe | Idempotent | Cacheable |
|---|---|---|---|
| Yes | Yes | Yes |
| Yes | Yes | Yes |
| Yes | Yes | No |
| Yes | Yes | No |
| No | Yes | No |
| No | Yes | No |
| No | No | Conditional* |
| No | No | Conditional* |
| No | No | No |
The upcoming QUERY HTTP method
Transmitting a large set of search parameters in a GET request becomes problematic at a certain size due to limitations on length and URI encoding. The less-than-ideal workaround has often been to use POST to send these parameters in the request body.
However, this presents its own set of challenges, as POST isn't idempotent and makes caching responses tricky.
That's where the proposed QUERY HTTP method steps in. It aims to keep all the benefits of GET—such as being safe, idempotent, and cacheable—while also embracing the flexibility of a POST request body for sending parameters.
This HTTP method is currently still in draft form but has already been assigned a "PROPOSED STANDARD" status as of January 7 of this year.
So, keep an eye out for this—it's likely we'll see it become an internet standard in the near future, potentially expanding the range of http request types available for API functionality.
What are the types of API?
While we've focused primarily on REST API methods, it's worth noting that there are several other types of APIs, each with its own set of methods and protocols.
Understanding these different types of api calls is crucial for developers working with various API protocols:
SOAP APIs: These use XML for message format and rely on SOAP (Simple Object Access Protocol) for transmitting data.
GraphQL APIs: A query language for APIs that allows clients to request exactly the data they need.
RPC APIs: Remote Procedure Call APIs that encode function calls as requests to remote servers.
Webhook APIs: Also known as reverse APIs, these send real-time data to other applications.
Open APIs: Publicly available APIs that allow developers to access certain data or functionality of an application.
Partner APIs: APIs exposed to strategic business partners, often requiring specific authorization.
Internal APIs: Used within an organization to share resources and functionality between different internal teams.
Composite APIs: These combine multiple API calls into a single request, useful for microservices architectures.
Each of these API types has its own set of methods and best practices for client-server communication, showcasing the diverse landscape of api functionality.
In the end, it's you, the user, who gives meaning to the API methods. These methods are essentially generic constructs and their actual behavior depends on how you choose to implement them in your RESTful APIs.
While REST principles provide guidelines for expected behaviors, a DELETE method can still be used to create data, while a POST method can be repurposed to retrieve data. The flexibility of these methods allows for creative solutions in API design and implementation.
Conclusion
I hope I was able to clearly explain the differences between the various API request types and help you understand when to use each one effectively. Now it's time to put that knowledge into practice and explore the world of API functionality.
If you're working with the Go programming language, I highly recommend checking out this guide on creating and documenting a REST API using Gin and Swagger. It'll solidify your understanding of building an API service and implementing various API functions.
For those of you who crave the nitty-gritty details about REST methods and http request types, you might also want to check out the original RFC published by IETF for an in-depth look at all the API methods discussed in this blog post.
Lastly, if you're eager to learn more, I’ve worked on a guide for GitHub beginners out here.
This article was first published on February 24th, 2024, and was improved by Emmanuel Isenah as of March 12th, 2025, to improve your experience and share the latest information.
