DEV Community

Cover image for cURL: A beginner's guide
SATYA SOOTAR
SATYA SOOTAR

Posted on

cURL: A beginner's guide

#networking #chaicode

Before we understand cURL, let’s understand what a server is.

A server is nothing but a machine, generally a computer that contains some resources, such as data or information that you can ask it to give(serve) to you, or you can give it some data to do some processing on it.

Imagine this: You(Client) are in a restaurant. You need food(Resource), and you tell the waiter(API) to take your order. The waiter noted down all the items and went to the kitchen(server). After the food is prepaired the waiter will bring the food to your table.

But what if you can talk directly to the kitchen and give an order of what you want? This is where cURL comes to the picture.

What is cURL?

cURL(Client URL) is a command-line tool for sending and receiving data and files using a URL syntax. You can send or receive data to or from the server without visiting the website or manually downloading files.

Image of cURL request flow

You might have heard about API clients such as Postman and Insomnia, which let you interact with the APIs using a Graphical user interface. cURL can let you do all that using a command-line interface.

cURL supports many kinds of transfer protocols, including HTTPS, HTTP, FTP, and SMTP. It also enables you to include cookies, set proxies, and add authentication credentials when making requests.

As a programmer, you will need cURL for:

  • Testing API
  • Debug problems with the web service
  • Automate tasks that involve fetching or sending files
  • Check if the server is working properly

Image of Browser request flow

Understanding request and response

As the word suggests request means you(Client) asking the server for some data or service. Whereas a response means the server sends you the data or the service you need. This request generally happens on the API.

An API (Application Programming Interface) is a set of rules and protocols that allows two different software programs to communicate and exchange data with each other.

API Request

The Request is generally the client's order to the server.
The key component of a typical API request include:

  • Endpoint URL: The specific address (URI) that identifies the resource the client wants to interact with (e.g.,https://api.example.com/users/45).

  • HTTP Method: An action verb that tells the server what to do with the resource. Common methods are:

    • GET: Retrieve data.
    • POST: Send data to create a new resource.
    • PUT: Update or replace an existing resource.
    • DELETE: Remove a resource.

  • Headers: Key-value pairs containing metadata about the request, such as authentication credentials (like an API key or token), the format of the body content (e.g., Content-Type: application/json), or caching instructions.

  • Request Body: Contains the actual data being sent to the server, typically used with POST, PUT, or PATCH requests (e.g., a JSON object with user details for a new account).

API response

The response is the server's reply after processing the request. It informs the client about the outcome and provides the requested data. Key components of an API response include:

  • Status Code: A three-digit HTTP code that indicates whether the request was successful or not. Examples include:

    • 200 OK: The request was successful.
    • 201 Created: The request was successful, and a new resource was created.
    • 404 Not Found: The requested resource could not be found.
    • 500 Internal Server Error: An error occurred on the server's side.

  • Headers: Additional metadata about the response, similar to request headers (e.g., Content-Type of the returned data, or session cookies).

  • Response Body: Contains the primary data requested by the client, such as a list of users or a weather forecast, usually formatted in JSON or XML. In the case of an error, it might contain a specific error message.

Make our first request to the server using cURL

Let's make a get request:

curl https://example.com
Enter fullscreen mode Exit fullscreen mode

Image of using curl to fetch the home page of example.com

What actually happened here:

  • You told cURL to contact the server at example.com
  • cURL sent a request asking for the homepage
  • The server responded with the HTML code for that page
  • cURL displayed that response in your terminal

In the above command the cURL returns the HTML only but not the header.

By adding a -i flag we can fetch the header file with HTML.

curl -i https://example.com
Enter fullscreen mode Exit fullscreen mode

Image of using curl command to fetch the header file

Let's make a post request:

In this request I will be using API from the Rest API example. Feel free to use these api for pratice purpose.

We will be using the command:

curl -X POST https://dummy.restapiexample.com/api/v1/create \
  -H "Content-Type: application/json" \
  -d '{"name":"satyasootar","salary":"1000","age":"20"}'
Enter fullscreen mode Exit fullscreen mode

Image of doing post request to the api using cURL

What actually happened here is:

  • You told cURL to contact the server at the dummy.restapiexample.com
  • cURL sent a request "Here is my data and so some processing with it".
  • After successful processing the server returns with a success message.
  • cURL displayed the message in your terminal

Let's break down this command:

  • -X POST: Specifies we're using the POST method (sending data)
  • -H "Content-Type: application/json": Tells the server we're sending JSON format
  • -d '...': The actual data we're sending (in JSON format)

Common beginniner mistakes while using cURL

  • Forgetting the protocol (http:// or https://)
  • Missing headers when calling APIs - Forgetting Content-Type or Authorization is super common.
  • Sending JSON without -d - Writing JSON but forgetting -d means no body is sent at all.
  • Using single quotes wrong on Windows - Single quotes work in Linux/macOS, but can break in Windows CMD.
  • Assuming curl behaves like Postman - Curl is raw and strict. No auto headers, no body formatting, no retries unless you ask for it.

Conclusion

cURL might look simple at first, but it gives you a very direct and honest way to communicate with servers. Once you understand how requests and responses actually work, many things start making sense automatically, whether it is Postman, browser dev tools, or even frontend frameworks. cURL helps you see what is really happening behind the scenes instead of hiding the details.

If you liked this explanation and are curious about how things work at a deeper level, I have written a few more blogs where I break down networking and internet concepts in a simple way. You can check out my posts on how TCP and UDP work and where each one is used, how TCP ensures reliable communication using the 3 way handshake, a clear explanation of DNS records, how DNS resolution works using the dig command, and an end to end breakdown of how the internet actually works from your device to the server.

Thank you for reading till the end. I am truly thankful for your time. If I have made any mistakes or if something can be explained better, please feel free to let me know in the comments. I am always open to learning and improving.

You can also connect with me here:

Top comments (0)