How to Use cURL for Sending Custom HTTP Headers

Introduction

When working with web servers, you often need to send HTTP requests that include custom headers. These headers can provide additional information or instructions to the server, such as specifying content types or authentication details. In this tutorial, we’ll explore how to use cURL—a powerful command-line tool—to send custom HTTP headers in your requests.

What is cURL?

cURL (Client URL) is a versatile command-line utility used for transferring data with URLs. It supports various protocols like HTTP, HTTPS, FTP, and more. One of its key features is the ability to customize HTTP requests by adding headers, making it an essential tool for developers who need to interact with web servers programmatically.

Sending Custom Headers with cURL

Basic Syntax

To send a custom header using cURL, you use the -H or --header option followed by the header name and its value. The syntax is:

curl -H "Header-Name: Header Value" [URL]

Here’s how to include multiple headers in a single request:

curl -H "Accept: application/json" -H "Content-Type: application/xml" [URL]

Examples

Example 1: Single Header

To send a custom header named X-MyHeader with the value 123 to www.google.com, use:

curl --header "X-MyHeader: 123" www.google.com

Example 2: Multiple Headers

If you want to send multiple headers, such as accepting JSON and setting a custom test header, execute:

curl --header "Accept: text/javascript" --header "X-Test: hello" -v www.google.com

The -v flag is used for verbose output, allowing you to see the request details.

Advanced Usage

Content Negotiation

To specify that your client can handle JSON responses, set the Accept header:

curl -i -H "Accept: application/json" http://hostname/resource

For XML content negotiation:

curl -H "Accept: application/xml" -X GET http://hostname/resource

Sending Data with POST Requests

To send data using a POST request, use the --data option:

curl --data "param1=value1&param2=value2" http://hostname/resource

For file uploads, use the --form or -F option:

curl --form "[email protected]" http://hostname/resource

RESTful HTTP Post

To perform a RESTful post with data from a file:

curl -X POST -d @filename http://hostname/resource

Authentication Headers

For logging into a site, you might need to handle authentication headers. Here’s an example of using cURL for login:

# Capture the response headers after posting credentials
curl -d "username=admin&password=admin&submit=Login" --dump-header headers http://localhost/Login
# Use the received cookies in subsequent requests
curl -L -b headers http://localhost/

Using cURL with PHP

In PHP, you can set custom headers using curl_setopt:

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "http://hostname/resource");
curl_setopt($ch, CURLOPT_HTTPHEADER, array('HeaderName: HeaderValue'));
// For multiple headers
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Header1: Value1',
    'Header2: Value2'
));

GET Requests with Parameters

When making a GET request with parameters, you can append them directly to the URL:

curl "http://localhost:3000/action?result1=gh&result2=ghk"

Or use the -G option to separate parameters from the URL:

curl -G "http://localhost:3000/action" --data-urlencode "result1=gh" --data-urlencode "result2=ghk"

Best Practices

Do Not Duplicate Headers: Avoid setting headers with names that already exist internally unless you are sure of the consequences.
Correct Syntax: Ensure no additional newlines or carriage returns are included in your header values.
Verbose Mode for Debugging: Use the -v flag to debug and verify the exact request being sent.

Conclusion

cURL is an indispensable tool for developers needing to send HTTP requests with custom headers. By mastering its syntax and options, you can effectively communicate with web servers, handle authentication, and negotiate content types, making your development process more efficient and robust.