The Different Types of API Requests

When you use an API, you're basically having a conversation with a system. But just like in real life, the way you ask matters. APIs follow a standard set of request "verbs" - these are called HTTP Methods. They tell the server what kind of action you want to perform.

Understanding HTTP Methods

HTTP methods are the foundation of API communication. Think of them as different ways to ask questions or give instructions to a server. Each method has a specific purpose and follows established conventions that both clients and servers understand.

The Conversation Analogy

Imagine you're talking to a librarian about books:

• "Can you show me the book about Python programming?" = GET request
• "I'd like to add a new book to your collection" = POST request
• "Please update the book's publication date" = PUT request
• "Just change the book's title, keep everything else the same" = PATCH request
• "Please remove this book from your collection" = DELETE request

Each request type serves a different purpose and expects a different response from the server.

GET - Reading Information

What GET Does

GET is the most common HTTP method, used to retrieve information from a server. It's like asking a question - you're requesting data without changing anything on the server.

Characteristics

• Safe: GET requests don't modify server data
• Idempotent: Multiple identical GET requests return the same result
• Cacheable: Responses can be stored and reused
• Read-Only: No side effects on the server

GET Request Examples

Basic GET Request

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

GET with Query Parameters

curl "https://api.example.com/users?page=1&limit=10&sort=name"

GET Specific Resource

curl https://api.example.com/users/123

GET with Headers

curl -H "Accept: application/json" https://api.example.com/users

When to Use GET

Use GET for:

• Retrieving user profiles
• Fetching product listings
• Getting search results
• Downloading files
• Reading configuration data
• Checking system status

Don't Use GET for:

• Submitting forms
• Creating new resources
• Updating existing data
• Deleting information
• Any operation that changes server state

POST - Creating New Resources

What POST Does

POST is used to submit new data to a server. It's like filling out a form and submitting it - you're sending information that the server will process and store.

Characteristics

• Not Safe: POST requests can modify server data
• Not Idempotent: Multiple identical POST requests may create multiple resources
• Not Cacheable: Responses typically shouldn't be cached
• Creates: Usually results in new resources being created

POST Request Examples

Basic POST Request

curl -X POST https://api.example.com/users

POST with JSON Data

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"name": "John Doe", "email": "john@example.com"}' \
  https://api.example.com/users

POST with Form Data

curl -X POST \
  -d "name=John Doe" \
  -d "email=john@example.com" \
  https://api.example.com/users

POST with File Upload

curl -X POST \
  -F "file=@profile.jpg" \
  -F "description=Profile picture" \
  https://api.example.com/upload

When to Use POST

Use POST for:

• Creating new user accounts
• Submitting contact forms
• Uploading files
• Processing payments
• Sending messages
• Any operation that creates new data

POST Response Examples

{
  "id": 456,
  "name": "John Doe",
  "email": "john@example.com",
  "created_at": "2024-01-15T10:30:00Z",
  "status": "active"
}

PUT - Complete Resource Replacement

What PUT Does

PUT is used to completely replace an existing resource. It's like rewriting an entire document - you provide all the data and the server replaces the old version with your new version.

Characteristics

• Not Safe: PUT requests modify server data
• Idempotent: Multiple identical PUT requests have the same effect
• Complete Replacement: Requires all resource data
• Overwrites: Existing data is completely replaced

PUT Request Examples

Basic PUT Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"id": 123, "name": "John Smith", "email": "john.smith@example.com"}' \
  https://api.example.com/users/123

PUT with Complete Data

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{
    "id": 123,
    "name": "John Smith",
    "email": "john.smith@example.com",
    "age": 30,
    "city": "Sydney",
    "country": "Australia"
  }' \
  https://api.example.com/users/123

When to Use PUT

Use PUT for:

• Updating complete user profiles
• Replacing entire documents
• Setting configuration values
• Complete resource updates
• When you have all the data

PUT vs POST

• PUT: "Replace the entire resource with this data"
• POST: "Create a new resource with this data"

PATCH - Partial Resource Updates

What PATCH Does

PATCH is used to make partial modifications to existing resources. It's like editing specific parts of a document - you only send the changes you want to make, not the entire resource.

Characteristics

• Not Safe: PATCH requests modify server data
• Idempotent: Multiple identical PATCH requests have the same effect
• Partial Updates: Only modifies specified fields
• Efficient: Sends only changed data

PATCH Request Examples

Basic PATCH Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"email": "newemail@example.com"}' \
  https://api.example.com/users/123

PATCH Multiple Fields

curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newemail@example.com",
    "city": "Melbourne"
  }' \
  https://api.example.com/users/123

PATCH with Nested Data

curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{
    "address": {
      "city": "Brisbane",
      "postcode": "4000"
    }
  }' \
  https://api.example.com/users/123

When to Use PATCH

Use PATCH for:

• Updating email addresses
• Changing user preferences
• Modifying specific fields
• Partial data updates
• When you only have some changes

PATCH vs PUT

• PATCH: "Update these specific fields"
• PUT: "Replace the entire resource"

DELETE - Removing Resources

What DELETE Does

DELETE is used to remove resources from a server. It's like asking someone to throw away a document - you're requesting that something be removed from the system.

Characteristics

• Not Safe: DELETE requests modify server data
• Idempotent: Multiple identical DELETE requests have the same effect
• Removes: Deletes the specified resource
• Confirmation: Usually returns confirmation of deletion

DELETE Request Examples

Basic DELETE Request

curl -X DELETE https://api.example.com/users/123

DELETE with Authentication

curl -X DELETE \
  -H "Authorization: Bearer token123" \
  https://api.example.com/users/123

DELETE with Confirmation

curl -X DELETE \
  -H "X-Confirm-Delete: true" \
  https://api.example.com/users/123

When to Use DELETE

Use DELETE for:

• Removing user accounts
• Deleting files
• Cancelling orders
• Removing comments
• Cleaning up temporary data

DELETE Response Examples

{
  "message": "User deleted successfully",
  "deleted_id": 123,
  "timestamp": "2024-01-15T10:30:00Z"
}

Other HTTP Methods

HEAD - Resource Information

HEAD is similar to GET but only returns headers, not the body. It's useful for checking if a resource exists or getting metadata without downloading the full content.

curl -I https://api.example.com/users/123

Use Cases

• Checking if a resource exists
• Getting file size before download
• Checking last modification date
• Validating authentication

OPTIONS - Available Operations

OPTIONS returns information about the communication options available for a resource.

curl -X OPTIONS https://api.example.com/users

Use Cases

• Discovering available HTTP methods
• Checking CORS policies
• Understanding API capabilities
• Pre-flight requests for complex operations

HTTP Method Comparison

Method Characteristics Summary

Method	Safe	Idempotent	Cacheable	Use Case
GET	Yes	Yes	Yes	Read data
POST	No	No	No	Create new resources
PUT	No	Yes	No	Complete replacement
PATCH	No	Yes	No	Partial updates
DELETE	No	Yes	No	Remove resources
HEAD	Yes	Yes	Yes	Get headers only
OPTIONS	Yes	Yes	No	Discover capabilities

When to Use Each Method

Reading Data

• GET: Retrieve information, search, download
• HEAD: Check existence, get metadata

Creating Data

• POST: Submit forms, create resources, process data

Updating Data

• PUT: Complete resource replacement
• PATCH: Partial resource updates

Removing Data

• DELETE: Remove resources, cancel operations

Discovering Capabilities

• OPTIONS: Check available operations

Practical Examples

User Management API

Create User (POST)

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "email": "jane@example.com"}' \
  https://api.example.com/users

Get User (GET)

curl https://api.example.com/users/123

Update User (PUT)

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"id": 123, "name": "Jane Smith", "email": "jane.smith@example.com"}' \
  https://api.example.com/users/123

Partial Update (PATCH)

curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"email": "jane.new@example.com"}' \
  https://api.example.com/users/123

Delete User (DELETE)

curl -X DELETE https://api.example.com/users/123

File Management API

Upload File (POST)

curl -X POST \
  -F "file=@document.pdf" \
  -F "description=Important document" \
  https://api.example.com/files

Download File (GET)

curl -o document.pdf https://api.example.com/files/456

Get File Info (HEAD)

curl -I https://api.example.com/files/456

Delete File (DELETE)

curl -X DELETE https://api.example.com/files/456

Best Practices

Method Selection

Choose the Right Method

• Use GET for reading data
• Use POST for creating new resources
• Use PUT for complete replacements
• Use PATCH for partial updates
• Use DELETE for removing resources

Avoid Common Mistakes

• Don't use GET for operations that change data
• Don't use POST when PUT or PATCH is more appropriate
• Don't use PUT for partial updates
• Don't use DELETE without confirmation for important resources

Request Design

Consistent Patterns

• Use plural nouns for collections (/users, /posts)
• Use singular nouns with IDs for specific resources (/users/123)
• Use consistent URL structures across your API
• Follow RESTful conventions when possible

Error Handling

• Return appropriate HTTP status codes
• Provide meaningful error messages
• Use consistent error response formats
• Include helpful debugging information

Conclusion

Understanding HTTP methods is fundamental to working with APIs effectively. Each method serves a specific purpose and follows established conventions that make API communication predictable and reliable.

By choosing the right HTTP method for each operation, you can:

• Communicate Clearly: Tell the server exactly what you want to do
• Follow Standards: Use established web conventions
• Improve Performance: Enable caching and optimisation
• Ensure Reliability: Make your API calls predictable and safe

Remember that HTTP methods are like a shared language between clients and servers. Using them correctly ensures that your API requests are understood and processed as intended, leading to more reliable and maintainable applications.

Start with the basic methods (GET, POST, PUT, DELETE) and gradually incorporate more advanced ones (PATCH, HEAD, OPTIONS) as your needs become more sophisticated.