DEV Community

Aditya Pratap
Aditya Pratap

Posted on

cURL

#api #beginners #cli #webdev

Client URL (cURL) is an open source command line tool for transferring data using URLs. It supports multiple protocols including HTTP, HTTPS, FTP, and more.

Why it's extensively used

  1. Testing Purposes
    Check if a server is up or debug it.

  2. API Development
    Send GET or POST requests directly to APIs.

    API can be thought of a carrier that takes in request and responds with a response.

  3. Automating requests
    Several developers use cURL to automate HTTP requests.

  4. Learning purposes
    Understand HTTP requests and responses within the terminal.

Initializing cURL Request

Let's hit this

curl -v https://example.com

  • v is a flag for 'verbose' output so that our curl command won't hide headers.

The response will be something like

> GET / HTTP/2
> Host: example.com
> User-Agent: curl/8.5.0
> Accept: */*
> 
< HTTP/2 200 
< content-type: text/html
Enter fullscreen mode Exit fullscreen mode

Here these ">" and "<" symbols mark something,

> Request headers (sent by curl)
< Response headers (sent by server)
Enter fullscreen mode Exit fullscreen mode

Request Headers 

> GET / HTTP/2
Enter fullscreen mode Exit fullscreen mode

This tells, We are using the GET HTTP method and HTTP/2 is the protocol's version.

> Host: example.com
Enter fullscreen mode Exit fullscreen mode

Informs the server which domain is requested.

> User-Agent: curl/8.5.0
Enter fullscreen mode Exit fullscreen mode

Identifies who is making the request, here it's done by curl.

> Accept: */*
Enter fullscreen mode Exit fullscreen mode

Says “I’ll accept any content type”

Response Headers 

< HTTP/2 200
Enter fullscreen mode Exit fullscreen mode

Again, HTTP/2 is the protocol we used.
200 is a HTTP status code, which means the request was successful.

Other frequently appearing status codes are:

HTTP Status Codes

< content-type: text/html
Enter fullscreen mode Exit fullscreen mode

Describes the content returned by server, here it is a HTML document.

GET Method (read only)

The GET method is an HTTP request method used to retrieve data from a server without modifying it.
BY default, curl uses GET method.

~$ curl https://api.freeapi.app/api/v1/public/randomjokes/joke/random
{"statusCode":200,"data":{"categories":["dev"],"id":75,"content":"Chuck Norris is the ultimate mutex, all threads fear him."},"message":"Random joke fetched successfully","success":true}
Enter fullscreen mode Exit fullscreen mode

Here, we requested the API for a random joke and it responded with a JSON object.

POST Method (read or write)

The POST request method is used to create or update data on the server.
We have to use '-X' flag to command curl to use POST.

~$ curl -X POST https://api.freeapi.app/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{"username":"doejohn","password":"test@123"}'
{
  "statusCode": 200,
  "success": true,
  "message": "User logged in successfully",
  "data": {
    "user": {
      "_id": "697c9e5caf1517d02a2fb058",
      "username": "doejohn",
      "email": "user.email@domain.com",
      "role": "ADMIN",
      "loginType": "EMAIL_PASSWORD",
      "isEmailVerified": false
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
Enter fullscreen mode Exit fullscreen mode

Here, we requested the API to login with out user and password and it responded with login info.

Common Beginner Mistakes

  • Missing https:// in URL
  • Forgetting Content-Type for JSON
  • Not knowing useful flags like "-A"
  • Expecting browser-like output
  • Ignoring status codes and headers

Top comments (0)