API Academy

Master Modern APIs

AI-powered

HTTP Verbs

Understanding the different HTTP methods and their purposes in RESTful APIs.

Essential Topic

3 Sections

What is HTTP Verbs? HTTP verbs (also called HTTP methods) define the action to be performed on a resource. They are the foundation of RESTful API design and tell the server what operation the client wants to perform.

Key Concepts

Idempotent

Multiple identical requests have the same effect as a single request

Safe Methods

Methods that don't modify server state (read-only operations)

CRUD Operations

Create, Read, Update, Delete - basic operations on data

Request Body

Data sent with the request, typically in POST/PUT/PATCH methods

Primary HTTP Methods

The most commonly used HTTP verbs in API development.

GET

Retrieve Data

Used to retrieve data from a server. Should be safe and idempotent - no side effects.

Example

GET /api/users/123
GET /api/products?category=electronics

Use Case:

Fetching user profiles, product listings, search results

POST

Create Resource

Used to create new resources on the server. Not idempotent - multiple calls create multiple resources.

Example

POST /api/users
Content-Type: application/json

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

Use Case:

Creating new users, submitting forms, uploading files

PUT

Update/Replace

Used to update or completely replace an entire resource. Idempotent operation.

Example

PUT /api/users/123
Content-Type: application/json

{
  "name": "John Smith",
  "email": "johnsmith@example.com"
}

Use Case:

Updating user profiles, replacing configuration settings

PATCH

Partial Update

Used to partially update a resource with only the changed fields.

Example

PATCH /api/users/123
Content-Type: application/json

{
  "email": "newemail@example.com"
}

Use Case:

Updating specific fields, toggling status, incremental changes

DELETE

Remove Resource

Used to delete a resource from the server. Idempotent operation.

Example

DELETE /api/users/123
DELETE /api/posts/456

Use Case:

Removing user accounts, deleting posts, clearing cache

Additional HTTP Methods

Less common but useful HTTP methods for specific scenarios.

HEAD

Get Headers Only

Similar to GET but returns only headers, no response body. Useful for checking resource existence.

Example

HEAD /api/users/123
# Returns headers only, no body

Use Case:

Checking if resource exists, getting metadata, cache validation

OPTIONS

Get Allowed Methods

Returns the HTTP methods supported by the server for a specific resource.

Example

OPTIONS /api/users
# Response: Allow: GET, POST, PUT, DELETE

Use Case:

CORS preflight requests, API discovery, method validation

CONNECT

Establish Tunnel

Establishes a tunnel to the server, typically used for HTTPS through proxies.

Example

CONNECT example.com:443 HTTP/1.1

Use Case:

Proxy connections, SSL tunneling

TRACE

Diagnostic Tool

Performs a message loop-back test along the path to the target resource.

Example

TRACE /api/users

Use Case:

Debugging, network diagnostics (rarely used in production)

Method Properties

Understanding the characteristics of different HTTP methods.

HTTP methods have different properties that affect how they should be used. Safe methods (GET, HEAD, OPTIONS) don't modify server state. Idempotent methods (GET, PUT, DELETE, HEAD, OPTIONS) can be called multiple times with the same result. Understanding these properties is crucial for proper API design and client implementation.

Best Practices

1
Use GET for retrieving data, never for operations that change server state
2
Use POST for creating resources and non-idempotent operations
3
Use PUT for complete resource replacement, PATCH for partial updates
4
Make sure DELETE operations are idempotent and safe to retry
5
Use appropriate status codes with each method (201 for POST success, 204 for DELETE success)
6
Include proper Content-Type headers when sending request bodies
7
Design URLs as nouns (resources) and use HTTP methods as verbs (actions)