Dule Martins's Blog

Using curl to test a REST API

Using curl to test a REST API

Dule Martins's photo
Dule Martins
·

5 min read

Table of contents

I believe the scientist Roy Fielding while creating the REST API, thought of the data it will transfer between web services. The number of services that depend on REST protocol for communication including cloud systems and microservices has increased, this made the requirement for REST API to take a serious turn in checking for the quality of a REST-based API.

This article is intended to introduce you to the basics of testing and interacting with a REST API using curl. As you follow these instructions, keep in mind that you made be using a different computer’s OS. But, in this article, I will be using a Windows terminal.

Prerequisites

Things needed to follow along as you read this article:

Let’s get started

curl is a “command-line tool for transferring data specified with URL syntax”. Open your terminal, I’m assuming you might have downloaded curl and got it installed on your machine. To download curl click here

curl works with HTTP request methods like GET, PUT, POST, and DELETE. Your terminal in Windows should look like this:

Terminal.PNG

Open and paste“curl -v”to display the version of your curl and to verify that you have installed it properly.

cURL-V.PNG

Let’s assume you are logged in to openweathermap and pick an API to test using curl.

OpenWeatherAPI.PNG

Let’s define some terms here, so it will help us get a grab on what we are doing and what we should be expecting. APIs are made up of parameters that define the response of an API call. In our case, we have:

  • “Lat” and “Lon”: Geographical coordinates (latitude, longitude).
  • “AppID”: Your unique API key (you can always find it on your account page)
  • “Mode”: Response format. Possible values are XML and HTML. If you don't use the mode parameter, the format is JSON by default.
  • “Units”: Units of measurement. standard, metric and imperial units are available. If you do not use the units parameter, standard units will be applied by default.

Next, paste your API URL into your terminal and press enter.

Get.PNG

This is an API test call with curl; the underlined parts are the parameters and methods used. We included a zip code = 95050, an app id/API key we got from our page on openweathermap, and Units = imperial.

Key.PNG That is our API key. The result of the curl API test call is shown below.

cURL-R.PNG

curl defaults to interacting with the server using a GET HTTP request method, which is used for reading data only. We will cover the other HTTP request methods later in this article.

curl API response

You notice the display we got from our activity with the terminal. That is a JSON file that holds information about the weather situation in Santa Clara, US. The syntax for a curl command is as follows:

curl [options] [URL...]

Options are added to a curl command to specify the output of an API response. In the case of the API call we made, we included the -X option and followed it with the GET HTTP request method.

curl options

There are other options that are added to curl when making an API request, here are the options that could be used when making requests:

  • curl -x, --request - specify the type of HTTP method to be used.
  • curl -I, --include - Include the response headers to be outputted.
  • curl -d, --data - Specify the data sent by the API as an output.
  • curl -h, --header - Additional header to be sent.
  • curl -v, --details - Output more detailed information about the API URL, is it also be used without a URL to show the version of curl being installed on your device.
  • curl -o, -- save - save the output as a file

Using different HTTP request methods with curl

Now that we know how to do a basic query of a REST API using curl, we can now use different HTTP methods in making queries.

Using the GET HTTP request method.

GET is the default method when making HTTP requests with curl. The requests made in the examples above were done with the Get request method.

Using the POST HTTP request method.

The POST HTTP request is not always in use, but while using the POST method you need to understand curl options and with the explanation given above that would help. Let’s dive in with this example and for the sake of this example, we will be using data from the JSONPlaceholder API. First, paste this

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

In your terminal and added a parameter like

curl https://jsonplaceholder.typicode.com/posts?userId=1

To filter the query.

Json.PNG

The following command will help makes a POST request using the data specified with the -d option:

D-option.PNG

Here we go with the response

curl-d.PNG

Using the PUT HTTP request method.

PUT HTTP request is used to update or replace a resource on the server about a data set when interacting with a REST API. It shares some similarities with POST, but in this case, we want to replace the resource with a specific data request.

put.PNG

I just pasted

curl -X PUT -d "userId=5&title=Hello World&body=Post body." https://jsonplaceholder.typicode.com/posts/5

In my terminal as shown above and here is the result

curl-d.PNG

We just added a new set of data to the resource file, and the data we added is displayed as a JSON file.

Using the DELETE HTTP request method.

There may be data you want to remove from the server, the HTTP Delete request method delivers that function using curl. Your syntax will include -X DELETE to specify the DELETE HTTP request method and a specific resource URL with parameters to delete. Here we go!

curl-x.PNG

The empty curly brackets represent an empty object in JSON meaning there is no data in the JSON file for posts/1.

Conclusion!

I just show you the basics around using curl to test a REST API, one benefit you get using curl is the fact that it makes you understand how to use the command line.

apicurlREST APITechnical writing