How to Use cURL to Test a Rails API
During my earlier programming days, when I needed to test an HTTP request to an API, it was in the process of developing a full-stack application, so I would simply perform the action on the front end (i.e. submitting a form) to see if the corresponding action occurred on the backend(i.e. a POST request to the database).
As it turns out, this is not the most efficient process, and, depending on the nature of the project, it may not even be an option. I figured there had to be a better way, and when I had to work on a strictly back-end Ruby on Rails API project, I discovered the better option: cURL.
What Is cURL?
cURL is an open-source software project that provides a client-side library and command-line tool that make it easy for users to send and receive data using URL transfer syntax. The name itself is a play on the combination of ‘Client’ and ‘URL.’
While cURL supports a variety of transfer protocols, in this blog post I will specifically be looking at how you can use curl, the command line tool, to perform HTTP requests on a Rails API.
Syntax
By default, curl will perform a GET request. So, if you’re running your API on localhost:3000, you could type curl http://localhost:3000/users in the command line to run a GET request, and you would receive a JSON object containing all of the users in your database.
That particular example doesn’t much that you couldn’t do with visiting that URL in your browser, so let’s take a look at few more complicated examples.
Examples
If you need to perform another HTTP request action such as POST, PUT, or DELETE, all you need to do is put -X in front of the request. For example, to delete the first user in your database, you would enter the following:
curl -X DELETE http://localhost:3000/users/1If you’re performing a POST request, you’ll likely need to be sending more information in the request, which is where the -d option comes in handy. If you were to create a new user using curl, you would enter the following:
curl -d "user[name]=Connor" http://localhost:3000/usersThis will send a POST request to the users URL with the parameter name set as the string “Connor”. Note that I did not have to include -X POST in the request. That is because when you include parameters using -d curl automatically makes the request a POST request.
Another important thing to watch out for is that you need to include -d before every parameter, not just once at the beginning of the request. This may or may not have tripped me up for a few minutes when I first started working with curl. If we say the users in our database have a few more attributes than in the previous example, then our POST request would look something like this.
curl -d "user[name]=Connor" -d "user[email]=connor123@mail.com" -d "user[password]=securepassword123" http://localhost:3000/usersPerforming POST requests like this in the command line is also a great, quick way to test out if your validations and error messages for new user creation are working properly.
The last major piece of curl syntax to know is that if you need to include any info such as an authorization key or Content Type in a header on your HTTP request, you can precede that info with -H.
Conclusion
The curl command line tool is a great feature of cURL that allows you to easily interact with a Rails API and perform HTTP requests to make sure all of your controller actions are working as desired at the specified routes. Hopefully you found this to be a helpful introduction to cURL if you’re unfamiliar with it, and, if you’d like to learn more, check out the following resources below.
