How to use curl for HTTP requests

Curl is a command line utility that was created in 1998 for transferring data using URLs. Fundamentally, curl allows users to create network requests to a server by specifying a location in the form of a URL and adding optional data.

curl (short for “Client URL”) is powered by libcurl – a portable client-side URL transfer library written in C.

Why use the curl command?

Common use cases for curl include:

• It can download and upload files
• It has great error logging
• It allows for quick endpoint testing
• It provides granular details which aides debugging
• It is portable and works with most operating systems
• It is an actively managed open-source tool that is battled tested with a large user base

Base curl command usage

The basic syntax for a curl command is:

1curl [OPTIONS] [URL]

HTTP Requests using curl

Curl provides native support for all HTTP requests methods: GET, POST, PUT, PATCH, DELETE, etc.

For all the following examples, the JSONPlaceholder API will be used.

Make a GET request

1curl https://jsonplaceholder.typicode.com/posts/1

OR

1curl -X GET https://jsonplaceholder.typicode.com/posts/1

NOTE: The -X flag is a shorthand for --request. It’s not required because the default value is GET.

Output:

1{
2  "userId": 1,
3  "id": 1,
4  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
5  "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
6}

In addition, an optional Accept header may be used:

1curl \
2	-H "Accept: application/json" \
3	https://jsonplaceholder.typicode.com/posts/1

Make a POST request

1curl -X POST -d "title=foo&body=test" \
2	https://jsonplaceholder.typicode.com/posts

In the example above, a new post titled foo with a body of test is created.

The default Content-Type of the request is: application/x-www-form-urlencoded

If a JSON payload is required, then the Content-Type header can be explicitly included:

1curl -X POST \
2	-H 'Content-Type: application/json' \
3	-d '{"title":"foo","body":"bar"}' \
4	https://jsonplaceholder.typicode.com/posts

Alternatively, a file may be specified (post.json):

1{
2    "title": "foo",
3    "body": "bar"
4}

1curl -X POST \
2	-H 'Content-Type: application/json' \
3	-d @post.json \
4	https://jsonplaceholder.typicode.com/posts

Output:

1{
2  "title": "foo",
3  "body": "bar",
4  "id": 101
5}

Make a PUT request

Similarly to POST, a PUT can use all the same options:

1curl -X PUT -d "title=foo&body=test" \
2	https://jsonplaceholder.typicode.com/posts/1

In the example above, post 1 is re-titled to foo and given a new body of test.

The default Content-Type of the request is: application/x-www-form-urlencoded

If a JSON payload is required, then the Content-Type header can be explicitly included:

1curl -X PUT \
2	-H 'Content-Type: application/json' \
3	-d '{"title":"foo","body":"bar"}' \
4	https://jsonplaceholder.typicode.com/posts/1

Alternatively, a file may be specified (post.json):

1{
2    "title": "foo",
3    "body": "bar"
4}

1curl -X PUT \
2	-H 'Content-Type: application/json' \
3	-d @post.json \
4	https://jsonplaceholder.typicode.com/posts/1

Output:

1{
2  "title": "foo",
3  "body": "bar",
4  "id": 1
5}

Make a PATCH request

Similarly to POST and PUT, a PATCH can use all the same options:

1curl -X PATCH -d "title=foo2" \
2	https://jsonplaceholder.typicode.com/posts/1

In the example above, post 1 is re-titled to foo2.

The default Content-Type of the request is: application/x-www-form-urlencoded

If a JSON payload is required, then the Content-Type header can be explicitly included:

1curl -X PATCH \
2	-H 'Content-Type: application/json' \
3	-d '{"title":"foo2"}' \
4	https://jsonplaceholder.typicode.com/posts/1

Alternatively, a file may be specified (post.json):

1{
2    "title": "foo2"
3}

1curl -X PATCH \
2	-H 'Content-Type: application/json' \
3	-d @post.json \
4	https://jsonplaceholder.typicode.com/posts/1

Output:

1{
2  "userId": 1,
3  "id": 1,
4  "title": "foo2",
5  "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
6}

Make a DELETE request

1curl -X DELETE https://jsonplaceholder.typicode.com/posts/1

Output:

1{}

Conclusion

curl is a powerful and versatile command line utility that offers a wide range of supporting features: multiple protocols, multiple options, data types, etc. HTTP requests are simple and reliable.