Curl is a command-line tool used for transferring data to or from a server. It supports various protocols, including HTTP, HTTPS, FTP, FTPS, and many more. One of the most useful features of curl is its ability to upload files to a server using the RESTful API. In this article, we will discuss how to perform a restful file upload with curl and the different options available.

What is RESTful API?

REST (Representational State Transfer) is an architectural style for designing networked applications. It is a lightweight, client-server, stateless, cacheable communication protocol that uses HTTP for data transfer. RESTful APIs are designed to be easily accessible and scalable, making them a popular choice for web services.

Uploading a File with Curl

To upload a file using curl, we need to use the -F option, which stands for “form.” This option allows us to specify the file to be uploaded and the form field name to which the file will be attached. The basic syntax for uploading a file with curl is as follows:

curl -F “form_field_name=@file_path” URL

Let’s break down this command:

• curl is the command-line tool we are using.
• -F is the option we are using to specify the file to be uploaded.
• “form_field_name=@file_path” is the form field name and the path to the file we want to upload.
• URL is the URL of the server where we want to upload the file.

For example, if we want to upload a file named “image.png” to a server with the URL “https://example.com/upload,” the command would look like this:

curl -F “[email protected]” https://example.com/upload

Additional Options

There are several additional options that we can use with curl to customize our file upload. Some of the most commonly used options are:

• -H to specify additional headers for the request.
• -u to specify a username and password for authentication.
• -X to specify the HTTP method to be used.
• -v to enable verbose mode, which displays more information about the request and response.

For example, if we want to upload a file with a custom header and authentication, the command would look like this:

curl -F “[email protected]” -H “Authorization: Bearer token” -u username:password https://example.com/upload

Upload File with cURL to AmetricX

Example: Upload CSV File

curl --location 'https://trial.ametricx.com/api/v1/file/upload' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR API KEY>' \
--form 'file=@"/C:/Users/AmetricX/metrics/ShippedToItems.csv"' \
--form 'file_id="<YOUR API KEY>"'

Response

{
    "task_id": "37f3c66a-816f-420e-bafe-195d63f74137"
}

Error Handling

If the file upload is successful, curl will return a response with a status code of 200. However, if there is an error, curl will return a status code of 400 or 500, depending on the type of error. To handle errors, we can use the -f option, which stands for “fail.” This option will cause curl to exit with an error code if the request fails.

Conclusion

Curl is a powerful tool for uploading files to a server using the RESTful API. With its various options and error handling capabilities, it provides a reliable and efficient way to transfer data. By following the steps outlined in this article, you can easily perform a restful file upload with curl and incorporate it into your workflow.

Have you used curl for file uploads before? Do you have any tips or tricks to share? Let us know in the comments.