Keywords: cURL | HTTP headers | command-line tool
Abstract: This article provides a detailed guide on using the cURL command-line tool to send HTTP headers, covering basic syntax, common use cases, and advanced techniques. Through multiple practical examples, it demonstrates how to set single and multiple headers, handle different content types, perform authentication, and debug requests. Based on highly-rated Stack Overflow answers and authoritative technical documentation, it offers a complete and practical cURL usage guide for developers.
Fundamentals of HTTP Headers
HTTP headers play a crucial role in client-server communication, transmitting metadata as name-value pairs, such as content type, authentication information, and caching directives. In cURL, the -H or --header option allows flexible addition, modification, or removal of these headers.
Basic Syntax and Single Header Setup
The basic command format for sending a single header with cURL is: curl -H "Header-Name: value" URL. For example, setting a custom user agent:
curl --header "X-MyHeader: 123" http://example.comThis command sends a header named X-MyHeader with value 123 to the specified URL. cURL automatically handles end-of-line markers, so users need not add newlines manually.
Multiple Headers and Content Negotiation
cURL supports sending multiple headers in a single request by repeating the -H option:
curl --header "Accept: text/javascript" --header "X-Test: hello" -v http://example.comThis example sets both Accept and X-Test headers. The -v option enables verbose mode, displaying sent requests and received responses for debugging.
Detailed Common Use Cases
GET Requests and Content Type Specification
Specifying expected response formats in GET requests:
curl -i -H "Accept: application/json" -H "Content-Type: application/json" http://hostname/resourceThe -i option ensures response headers are included in the output. For XML format, simply adjust header values:
curl -H "Accept: application/xml" -H "Content-Type: application/xml" -X GET http://hostname/resourcePOST Requests and Data Submission
Sending form data:
curl --data "param1=value1¶m2=value2" http://hostname/resourceFile upload:
curl --form "fileupload=@filename.txt" http://hostname/resourceRESTful-style POST request:
curl -X POST -d @filename http://hostname/resourceAuthentication and Session Management
Using basic authentication headers:
curl -H "Authorization: Bearer my-access-token" http://hostname/resourceFor form-based login, combine with --dump-header to save sessions:
curl -d "username=admin&password=admin&submit=Login" --dump-header headers http://localhost/Login
curl -L -b headers http://localhost/Advanced Header Manipulation Techniques
Header Removal and Empty Value Setting
Removing headers added by cURL by default (e.g., User-Agent):
curl -H "User-Agent:" http://example.comSending headers with empty values:
curl -H "Custom-Header;" http://example.comViewing and Saving Response Headers
Retrieving only response headers:
curl -I http://example.comViewing both response headers and content:
curl -i http://example.comSaving headers to a file:
curl -D headers.txt -o content.txt http://example.comDebugging and Error Handling
Use the -v option for verbose output to help identify header format errors or server issues. Common problems include misspelled header names, extra spaces, or unsupported header types. Always check server response status codes and error messages.
Practical Application Scenarios
cURL's header functionality is extremely useful in API testing, web scraping, and automation scripts. By customizing headers like User-Agent, Referer, or API keys, developers can simulate different client behaviors or meet specific service requirements. Combining conditional headers such as If-Modified-Since further optimizes data retrieval efficiency.
Conclusion
Mastering HTTP header operations with cURL significantly enhances development efficiency. From simple header settings to complex multi-header management, cURL provides flexible and powerful tools. By practicing the examples above, developers can quickly adapt to various network communication needs, ensuring request accuracy and security.