# Getting Started with cURL ## **What is cURL** cURL (client URL) is **a free and open-source command-line tool and library for transferring data** to or from a server using various network protocols and URL syntax. It is widely used by developers and system administrators for tasks like testing APIs, downloading/uploading files, and debugging network connections. The cURL software project consists of two main parts:  * `libcurl`: A client-side URL transfer library that provides the core functionality and supports a wide range of protocols. It has bindings for over 50 programming languages and is used behind the scenes in countless software applications, devices, and operating systems. * `curl`: The command-line tool that provides a text-based interface for interacting with `libcurl`. Users type `curl` commands into a terminal or command prompt to perform data transfer operations.  * **Basic Syntax** The basic syntax for the command-line tool is `curl [options] [URL]`.  For example: * To fetch the HTML content of a webpage and display it in the terminal:**bash** ```plaintext curl ``` [**bash**](https://example.com/) ```plaintext https://www.example.com ``` **bash** * To download a file and save it with a specific filename:**bash** ```plaintext curl -o myfile.zip https://www.example.com/myfile.zip ``` * To send a POST request with data:**bash** ```plaintext curl -d "param1=value1¶m2=value2" https://www.example.com/api/endpoint ``` * ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1769620029417/9830ad74-45b7-4a8b-9c02-677c6a56ba0c.png align="center") * ##  **Why programmers need cURL** * `curl` (Client URL) is a **command-line tool** used to **send requests to URLs and receive responses**. Programmers use it because it lets them **talk to web servers directly**, without a browser or app .`curl` is the easiest way to test and interact with APIs and web services. ## Main reasons programmers use `curl` ### 1️⃣ To test APIs quickly APIs are everywhere. With `curl`, you can: * Send **GET, POST, PUT, DELETE** requests * Pass headers, tokens, and data Example: ```plaintext curl https://api.example.com/users ``` 👉 Instant response, no frontend needed. --- ### 2️⃣ To debug backend issues When something breaks, `curl` helps answer: * Is the server responding? * Is the endpoint correct? * Is authentication working? This separates **frontend bugs from backend bugs**. --- ### 3️⃣ To understand HTTP deeply Using `curl` teaches: * HTTP methods * Status codes (200, 404, 500) * Headers * Cookies * Authentication It’s like **seeing HTTP without filters**. --- ### 4️⃣ To automate tasks `curl` works in: * Shell scripts * CI/CD pipelines * Cron jobs Used for: * Health checks * Triggering webhooks * Uploading/downloading data --- ### 5️⃣ To work without a browser Servers, containers, and remote machines often **don’t have browsers**. `curl` works everywhere. --- ### 6️⃣ To test security & auth Programmers use `curl` to test: * JWT tokens * OAuth headers * HTTPS / TLS * Rate limits Example: ```plaintext curl -H "Authorization: Bearer TOKEN" https://api.example.com ``` --- ## Simple analogy * Browser = luxury car (lots of features) * `curl` = screwdriver (direct, precise, powerful) ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1769620175091/f7a22a8d-c043-4376-9033-7221fe04f714.png align="center") ## **Making your first request using cURL** * `curl` is a command-line tool that lets you **send HTTP requests** and **see server responses directly**. * 1️⃣ Your first `curl` command (GET request) Open Terminal / Command Prompt and type: ```plaintext curl https://example.com ``` ### What happens? * `curl` sends a **GET request** to [`example.com`](http://example.com) * The server responds with **HTML** * `curl` prints the response on your screen 👉 Congrats 🎉 you just made your **first HTTP request**. --- ## 2️⃣ Understanding what just happened * **URL** → where the request is sent * **GET** → default HTTP method * **Response body** → website content returned by the server --- ## 3️⃣ See response headers (important!) ```plaintext curl -i https://example.com ``` This shows: * HTTP status code (`200 OK`) * Headers like `Content-Type`, `Server` * Response body --- ## 4️⃣ Pretty-view the request (debug mode) ```plaintext curl -v https://example.com ``` Shows: * Request headers * TLS handshake * Full request–response flow Great for learning HTTP 🔍 --- ## 5️⃣ Making a request to an API ```plaintext curl https://api.github.com ``` You’ll get **JSON** instead of HTML. --- ## 6️⃣ Saving the response to a file ```plaintext curl -o page.html https://example.com ``` Now the website is saved as `page.html`. --- ## Simple mental model ```plaintext curl → sends request server → sends response terminal → shows output ``` --- ## **Understanding request and response** * **The request-response model is the foundational communication pattern in client-server architecture (such as the web), where a client initiates a message (request) to a server, and the server processes the message and sends data or a status back in a subsequent message (response)**. This process is facilitated by protocols like HTTP (Hypertext Transfer Protocol).  **The Request** A request is a message sent by a client (e.g., a web browser or application) to a server to ask for a specific action or resource. An HTTP request is comprised of several key components:  * **URL/Endpoint:** The address that specifies the location of the resource being requested (e.g., `https://example.com/data`). * **Method (Verb):** An indicator of the desired action the client wants to perform. Common methods include: * `GET`: Retrieves data from a specified resource. * `POST`: Submits data to be processed to a specified resource, often creating a new entry. * `PUT`: Updates or replaces an existing resource with the provided data. * `DELETE`: Removes a specified resource. * **Headers:** Metadata providing additional information about the request, such as the client's browser type, content types, or authentication tokens. * **Body (Optional):** Contains the actual data being sent to the server, typically used with `POST` or `PUT` methods (e.g., form data, JSON object).  **The Response** A response is the message sent back by the server to the client after processing the request. An HTTP response also has several key components:  * **Status Code:** A three-digit number indicating the outcome of the request. * `200 OK`: The request has succeeded. * `404 Not Found`: The requested resource could not be found. * `500 Internal Server Error`: A server-side error prevented the request from being fulfilled. * **Headers:** Metadata about the response, such as the content type being returned (e.g., `Content-Type: application/json`), caching instructions, or server details. * **Body (Optional):** Contains the main content requested by the client, such as HTML for a webpage, a JSON list of data, or an image file.  **The Request-Response Cycle** The interaction follows a specific flow:  1. **Client Sends Request:** The client initiates the communication by sending a request to the server. 2. **Server Parses and Processes:** The server receives, parses, and processes the request. This may involve running application logic or querying a database. 3. **Server Sends Response:** The server formulates a response (including status code, headers, and body) and sends it back to the client. 4. **Client Handles Response:** The client receives the response, parses it, and uses the information (e.g., renders the webpage, displays data, or handles an error).  ## **Using cURL to talk to APIs** APIs are just **URLs that accept HTTP requests and return data (usually JSON)**. `curl` lets you **talk to APIs directly from the command line**, without any app or browser. * ## 1️⃣ Basic API request (GET) ```plaintext curl https://api.github.com ``` * Sends a **GET request** * Receives **JSON response** * No authentication required --- ## 2️⃣ Sending headers (very common) APIs often require headers like `Accept` or `Authorization`. ```plaintext curl -H "Accept: application/json" https://api.example.com/users ``` --- ## 3️⃣ Authentication with token (JWT / Bearer) ```plaintext curl -H "Authorization: Bearer YOUR_TOKEN" \ https://api.example.com/profile ``` Used for: * Logged-in users * Secure APIs --- ## 4️⃣ Sending data (POST request) ```plaintext curl -X POST https://api.example.com/users \ -H "Content-Type: application/json" \ -d '{"name":"Alex","email":"alex@example.com"}' ``` * `-X POST` → HTTP method * `-d` → request body * JSON sent to API --- ## 5️⃣ Updating data (PUT / PATCH) ```plaintext curl -X PUT https://api.example.com/users/1 \ -H "Content-Type: application/json" \ -d '{"name":"Alex Updated"}' ``` --- ## 6️⃣ Deleting data (DELETE) ```plaintext curl -X DELETE https://api.example.com/users/1 ``` --- ## 7️⃣ Debugging API calls (very important) ```plaintext curl -v https://api.example.com ``` Shows: * Request headers * Response headers * Status codes * Errors --- ## Common API status codes * `200` → Success * `201` → Created * `400` → Bad request * `401` → Unauthorized * `404` → Not found * `500` → Server error --- ## Simple analogy * API = waiter * `curl` = you placing the order * Response = food served ## **Common mistakes beginners make with cURL** When starting with `curl`, small mistakes can cause **confusing errors**. Here are the **most common beginner mistakes**, explained simply—with fixes. * ## 1️⃣ Forgetting the HTTP method `curl` uses **GET by default**. Beginners expect POST/PUT but don’t specify it. ❌ Wrong: ```plaintext curl https://api.example.com/users ``` ✅ Fix: ```plaintext curl -X POST https://api.example.com/users ``` --- ## 2️⃣ Missing `Content-Type` header APIs often expect **JSON**, but beginners send data without headers. ❌ Wrong: ```plaintext curl -X POST -d '{"name":"Alex"}' https://api.example.com ``` ✅ Fix: ```plaintext curl -X POST \ -H "Content-Type: application/json" \ -d '{"name":"Alex"}' \ https://api.example.com ``` --- ## 3️⃣ Wrong JSON format JSON must use **double quotes**. ❌ Wrong: ```plaintext -d '{name: Alex}' ``` ✅ Fix: ```plaintext -d '{"name":"Alex"}' ``` --- ## 4️⃣ Not escaping quotes (Windows users 😅) Command Prompt requires escaping quotes. ❌ Wrong: ```plaintext -d '{"name":"Alex"}' ``` ✅ Fix (CMD): ```plaintext -d "{\"name\":\"Alex\"}" ``` --- ## 5️⃣ Forgetting authentication Protected APIs return `401 Unauthorized`. ❌ Mistake: ```plaintext curl https://api.example.com/profile ``` ✅ Fix: ```plaintext curl -H "Authorization: Bearer TOKEN" https://api.example.com/profile ``` --- ## 6️⃣ Not checking the response status Beginners only look at the body, not the **status code**. ✅ Fix: ```plaintext curl -i https://api.example.com ``` or ```plaintext curl -v https://api.example.com ``` --- ## 7️⃣ Assuming curl failed when it didn’t Sometimes `curl` works but **returns no output**. ❌ Confusion: ```plaintext curl https://api.example.com/delete ``` 👉 API returned `204 No Content` (success). --- ## 8️⃣ Forgetting HTTPS Many APIs **reject HTTP**. ❌ Wrong: ```plaintext curl http://api.example.com ``` ✅ Fix: ```plaintext curl https://api.example.com ``` --- ## Pro beginner tip Always debug with: ```plaintext curl -v ``` It shows **everything**. ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1769620252006/432ae8df-9e6f-4e15-a7d9-c28215253f94.png align="center") ---