HTTP Methods

Master the five HTTP methods that control what happens when your API receives a request.

GitHub's API handles over 50 million requests daily. Each request carries one crucial piece of information: what action the client wants to perform. That single word — GET, POST, PUT, PATCH, or DELETE — determines everything about how the server responds.

HTTP methods eliminate guesswork. Without them, your API would receive a request to /api/users/123 and have no idea what the client wants. Should it return user data? Delete the user? Update their information? Methods solve this ambiguity by declaring intent upfront.

Think of HTTP methods as verbs in a sentence. The URL is the noun — the resource you want to work with. The method is the action you want to perform on that resource. This verb-noun combination creates a clear, predictable language that developers worldwide understand instantly.

Modern web applications rely on this predictability. Stripe processes millions in payments because their API methods work exactly as expected. POST creates charges, GET retrieves transaction data, DELETE cancels subscriptions. No surprises, no ambiguity.

The Five Essential Methods

Every HTTP method serves a specific purpose, and understanding these purposes shapes how you design APIs that developers actually want to use.

The five methods you need to master each map to common database operations. This mapping is not accidental — it reflects how most software applications work. You create data, read it, update it, and sometimes delete it. HTTP methods provide a standardized way to express these intentions over the network.

But methods are more than just labels. They carry semantic meaning that affects caching, browser behavior, and developer expectations. GET requests can be cached and bookmarked. POST requests cannot. PUT requests can be repeated safely. DELETE requests remove data permanently.

DELETE rounds out the set, though it is less commonly implemented in public APIs. Many services prefer to mark records as inactive rather than removing them permanently. Slack channels get archived, not deleted. Twitter accounts get suspended, not erased.

GET Method Deep Dive

GET is the workhorse of the web — every webpage, image, and API call for data uses GET requests by default.

When you type a URL into your browser, you are making a GET request. When JavaScript fetches user profile data, it uses GET. When mobile apps load a list of products, they send GET requests to the server. This method handles the vast majority of web traffic.

GET requests carry their parameters in the URL itself, not in a request body. You have seen this pattern countless times: /search?q=javascript&page=2. Everything after the question mark represents data sent to the server. This approach makes GET requests bookmarkable and shareable.

The APIForge Backend team needs to build an endpoint that returns project statistics for their dashboard. Since this operation only reads data without modifying anything, GET is the natural choice.

GET requests must be idempotent — calling them multiple times produces the same result without side effects. This property enables aggressive caching and makes APIs more reliable. If your GET request modifies data, you are violating HTTP standards and will encounter unexpected behavior in browsers and proxy servers.

Search engines and web crawlers exclusively use GET requests when indexing content. If your API endpoint should be discoverable through search, GET is your only option. This explains why most public API documentation uses GET for their examples — it works in browsers without additional tools.

POST Method Deep Dive

POST handles the heavy lifting of data creation and any operation that changes server state.

Unlike GET requests, POST sends data in the request body, not the URL. This approach supports large payloads and keeps sensitive information out of browser history and server logs. When you submit a form on a website, the browser typically sends a POST request with the form data in the body.

POST requests are never cached by browsers or proxy servers. Each POST request is treated as unique and potentially state-changing. This behavior protects against accidental duplicate submissions that could create unwanted side effects.

The APIForge Product team needs to create new feature requests when users submit feedback through their dashboard. This operation creates new data in the system, making POST the appropriate choice.

POST requests are not idempotent — sending the same POST request twice might create two identical resources. This is why payment forms often disable the submit button after clicking, preventing accidental duplicate charges. Stripe and other payment processors implement sophisticated duplicate detection to handle this common problem.

The flexibility of POST makes it a catch-all for operations that do not fit neatly into other methods. Some APIs use POST for complex search queries that would create URLs too long for GET. Others use POST for operations like "send email" or "process payment" that do not map directly to resource creation.

PUT vs PATCH Methods

The difference between PUT and PATCH confuses many developers, but understanding it prevents data loss and API design mistakes.

PUT replaces an entire resource with the data you send. If you send a user object with only the email field, PUT will remove all other fields from the stored user record. PATCH applies only the changes you specify, leaving other fields untouched.

This distinction matters enormously in real applications. Imagine updating a user profile with dozens of fields — name, email, preferences, settings, metadata. With PUT, you must send the complete current state plus your changes. With PATCH, you send only the fields that changed.

The APIForge Frontend team needs to update user preferences when someone changes their notification settings. They could use PUT and send the entire user object, or PATCH and send just the preference changes.

Aspect	PUT	PATCH
Scope	Replaces entire resource	Updates specific fields
Data Required	Complete resource representation	Only changed fields
Bandwidth	Higher — sends all fields	Lower — sends minimal data
Risk of Data Loss	High if incomplete data sent	Low — preserves untouched fields
Idempotency	Idempotent	Idempotent
Best For	Complete resource replacement	Partial updates, mobile apps

Both PUT and PATCH are idempotent — you can safely retry them if a network error occurs. This property makes them more reliable than POST for update operations. Many mobile applications prefer PATCH because it minimizes data usage when updating resources over cellular connections.

PUT has an interesting behavior: if you send a PUT request to a URL that does not exist, the server should create a new resource at that location. This makes PUT useful for APIs where clients can specify their own resource identifiers. PATCH, however, typically returns an error if you try to patch a non-existent resource.

DELETE Method and Soft Deletes

DELETE requests remove resources, but most production APIs implement soft deletion instead of permanently erasing data.

Hard deletion means the data disappears forever. Soft deletion marks records as inactive while preserving the actual data. This approach enables features like "restore deleted items" and maintains data integrity when other systems reference the deleted resource.

Consider what happens when you delete a user account. If other users have sent messages to that account, hard deletion would break the message history. Soft deletion preserves the account data while preventing the user from logging in or appearing in active user lists.

The APIForge Security team needs to handle account deletion requests while maintaining audit trails for compliance. They implement soft deletion by adding a deleted_at timestamp field instead of removing records.

DELETE requests should be idempotent — deleting an already-deleted resource succeeds without error. This behavior prevents client code from breaking when retrying failed delete operations. Most APIs return a 204 No Content status for successful deletions, regardless of whether the resource existed.

Some APIs avoid DELETE entirely, preferring to update resources to an inactive state using PATCH requests. This approach makes the soft deletion explicit and allows for more nuanced states like "archived," "suspended," or "pending deletion." GitHub uses this pattern for repository deletion — repositories become private and scheduled for removal rather than disappearing immediately.

Method Safety and Idempotency

Understanding which methods are safe and idempotent helps you design reliable APIs that work predictably with browsers, caches, and proxy servers.

Safe methods do not modify server state. GET is safe — you can call it repeatedly without changing anything. POST is not safe — each call might create a new resource or trigger side effects. This distinction affects how browsers, search engines, and caching systems treat your API endpoints.

Idempotent methods produce the same result when called multiple times. PUT is idempotent — setting a user's email to the same value repeatedly has the same effect as doing it once. POST is not idempotent — submitting the same form data multiple times might create duplicate records.

These properties combine to determine how systems can safely interact with your API. Browsers can cache GET responses and prefetch GET requests without asking permission. They cannot do the same with POST requests because POST might change server state.

Violating these semantic rules creates unpredictable behavior. If you use GET for operations that modify data, browser prefetching might trigger unintended changes. If you make POST requests non-idempotent when they could be idempotent, you make error recovery more complex for API consumers.

CDNs and proxy servers rely on these properties to optimize performance. Cloudflare caches GET responses aggressively but never caches POST responses. Understanding these behaviors helps you choose the right method for each endpoint and avoid surprising your API consumers.

Real-World Method Patterns

Successful APIs follow predictable patterns when mapping operations to HTTP methods, making them intuitive for developers to learn and use.

Resource-oriented APIs use methods consistently across all endpoints. GET /users lists users, POST /users creates a user, GET /users/123 retrieves user 123, PATCH /users/123 updates user 123. This consistency reduces the learning curve for new API consumers.

Action-oriented operations require more thought. Sending an email, processing a payment, or generating a report does not map neatly to resource manipulation. Most APIs use POST for these operations, treating them as commands rather than resource modifications.

The APIForge DevOps team designs deployment endpoints that trigger complex workflows. They use POST for deployment operations because each deployment creates a new deployment record and triggers side effects across multiple systems.

Bulk operations challenge traditional method mappings. Updating hundreds of records with individual PATCH requests creates unnecessary network overhead. Many APIs provide bulk endpoints that accept arrays of operations, typically using POST because the request does not map to a single resource.

Search functionality demonstrates another common pattern. Simple searches work well with GET — the search parameters go in the URL, making results bookmarkable. Complex searches with many filters or large payloads require POST to avoid URL length limits and improve request structure.

File uploads almost always use POST or PUT, depending on whether the client or server determines the file identifier. PUT works when clients specify the filename or ID, while POST works when servers generate identifiers automatically. Large file uploads might use specialized methods or streaming protocols, but they start with these standard HTTP methods.

Quiz