How to Send a DELETE Request Using cURL

If you need to interact with RESTful APIs that support deleting resources, cURL is a handy command-line tool for the job. In this guide, we‘ll walk through how to craft and send HTTP DELETE requests using cURL.

What is cURL?

cURL (client URL) is an open source software library and command-line tool for transferring data using various network protocols. It is widely used for interacting with web servers and APIs from the command line or within shell scripts.

cURL supports a wide range of protocols including HTTP, HTTPS, FTP, SFTP, and many others. It provides options for specifying request methods, headers, authentication, URL parameters, request bodies, and more.

HTTP Methods Primer

Most modern web APIs are built on RESTful design principles and use HTTP as the underlying protocol. The key HTTP methods you‘ll encounter are:

• GET – Retrieve a resource
• POST – Create a new resource
• PUT – Replace an existing resource
• PATCH – Partially update an existing resource
• DELETE – Remove a resource

The DELETE method is used when you want to delete a resource from the server. For example, if you have an API endpoint for managing user accounts, you might send a DELETE request to /users/123 to delete the user with ID 123.

Sending a DELETE Request with cURL

The basic structure of a cURL command to send a DELETE request is:

curl -X DELETE [options] [URL]

The -X flag specifies the HTTP method to use. Other commonly used options include:

• -H – Set request headers, such as authorization tokens or content types
• -d – Include a request body (though not commonly used with DELETE)
• -u – Specify a username and password for authentication
• -i – Include the response headers in the output

For example, let‘s say we want to delete a todo item with ID abc123 from a fictional TODO list API. The cURL command would look like:

curl -X DELETE https://api.example.com/todos/abc123 \
  -H ‘Authorization: Bearer my-access-token‘

This sends a DELETE request to https://api.example.com/todos/abc123 with an Authorization header containing an access token for authentication.

Handling Responses

After sending a DELETE request, you‘ll want to inspect the HTTP response code to determine if it was successful or not. Some common response codes for DELETE requests are:

• 200 OK – The resource was deleted successfully
• 204 No Content – The resource was deleted successfully and the response body is empty
• 401 Unauthorized – Authentication failed or authorization token is missing
• 404 Not Found – The specified resource does not exist

You can use the -i flag with cURL to include the response headers in the output, which will show the status code. For example:

curl -i -X DELETE https://api.example.com/todos/abc123

Using cURL in Scripts

Since cURL is a command-line tool, it‘s easy to use within shell scripts to automate API interactions. For example, you could write a script to delete a set of resources based on a list of IDs:

#!/bin/bash

ids=(abc123 def456 ghi789) 

for id in "${ids[@]}" 
do
  curl -i -X DELETE https://api.example.com/todos/$id \
    -H ‘Authorization: Bearer my-access-token‘
done

This simple script loops through an array of todo IDs and sends a DELETE request for each one.

Considerations and Best Practices

When working with DELETE requests and API design in general, here are some things to keep in mind:

• Sending a DELETE request is permanent, so provide confirmation flows in your application to prevent accidental deletion of data.

• RESTful APIs often use the concept of "soft delete" where deleted items are marked as inactive rather than permanently removed. This allows for recovery of deleted data if needed.

• Make sure your API endpoints properly authorize clients and validate ownership/permissions before allowing deletion of resources.

• Use appropriate response codes and include informative error messages in the response bodies if a deletion fails.

• Avoid requiring request bodies for DELETE requests. Any parameters should be in the URL or headers.

• Be clear in your API documentation about what DELETE requests do, what response clients can expect, and any side effects to be aware of.

While we focused on cURL in this guide, the concepts apply to sending DELETE requests with any tool or language. Most web frameworks and libraries provide an easy way to issue DELETE requests to an API as well.

Conclusion

Sending DELETE requests with cURL is a fundamental skill for anyone working with RESTful web APIs. With the -X DELETE option and support for headers, authentication, and more, cURL provides a simple yet powerful way to delete resources from the command line. Use it in one-off requests or within scripts for automation.

Always be mindful of the power of DELETE and make sure to implement proper access controls and confirmations within your APIs and applications. Happy deleting!