The http protocol is the main protocol used on the web, and because of its widespread adoption it is also used in IOT applications.

Many IOT applications like the Thingsboard Dashboard support both http and MQTT.

In this tutorial we will start with a general introduction to cURL and show examples of using cURL to get and POST data.

What is Curl?

The cURL command can be used for testing a variety of protocols including http .

In IOT applications it’s main use is for retrieving data and posting data to web based APIs using HTTP.

Curl is available for most clients and you can download it here.

In this tutorial we will be covering a number of examples that will help you become familiar with curl and the HTTP protocol.

cURL Basics

The curl command is controlled by optional command line switches or options.

You should be aware that some are lower case and some upper case.

There are two formats used they are:

A short form which is a single hyphen followed by a letter e.g. curl websiteurl -v
Long form of Two hyphens followed by a word e.g. curl websiteurl –verbose

Note: Not all options have a short form and some options require additional data.

If the options don’t require additional data you can combine the short form options.

so curl websiteurl -v -L is the same as curl websiteurl -vL

Options can come before or after the websiteurl so:

curl www.testsite.com -v is the same as curl -v www.testsite.com

Here is the curl manual page which covers all of the options in detail.

Using Curl Examples:

Requests

The http protocol supports several request methods. the most common method is the GET Method which curl uses by default.

This is the same method used by your web browser when you visit a website.

Example Usage -GET

The most basic usage is to retrieve a page from a website.

Curl uses the GET method by default so you don’t need to set the option.

Several options are useful.Here we will use curl to view:

webpage content – curl pageurl
webpage content and headers – curl pageurl -v
webpage receive headers only – curl pageurl -l (capital i)
webpage speed – curl pageurl –trace-time

Example webpage content and headers – curl pageurl -v

curl-example-1

Using With the Postman Echo API

The postman-echo api is an online test API that you can use to get familiar with APIs and curl.

APIs requests have an endpoint url e.g

https://postman-echo.com/get

The endpoint is effectively a function that is called when the web server receives a request on that endpoint.

You can also pass parameters to the endpoint by appending them to the url using the format shown below:

Passing-parameters-url

Notice:

The use of a question mark to separate the API endpoint from the parameters
The parameters are keyword pairs
Multiple parameters use a & to separate them

What is returned depends on the endpoint. In the example above the endpoint returns the parameters you sent, and the header that you sent in the request.

Using-Curl-API-Example

Tip: For a GET request you can also use a web browser.

get-request-web-browser

cURL POST Method

This is used for sending data to a server. It is commonly used for sending form data to a web server but for APIs it is typically used for sending JSON data or key/value pairs.

The data for the post method is contained in the body and is indicated by the –data or -d switch.

You will also generally need to specify the data type using the –header option common data types are:

multipart/form-data
application/x-www-form-urlencoded
application/json

For sending key/pair data as a string then use the header option.:

Content-Type:application/x-www-form-urlencoded

e.g. using the postman-echo api

curl  --request POST "https://postman-echo.com/post"   --data "foo1=bar1&foo2=bar2" \
--header "Content-Type:application/x-www-form-urlencoded"

For sending JSON encoded data use:

–header “Content-Type:application/json”

In this example I will be using the Thingboard IOT demo dashboard.

The thingsboard website give the various formats supported and example curl commands.

Unfortunately these didn’t work on windows until I escaped the quotes on the data keys and values.

The format I used was the simple format

{"key1":"value1", "key2":"value2"}

The data needs to be JSON encoded .

The Thingsboard dashboard that I am using has two devices a light and door. The JSON data looks like this

“{, \”main-light\”:\”OFF \”,\”main-door\”:\”OPEN\”}”

Notice I had to escape the quotes around the keys and values.

Here is a command example

Summary

The curl command is a test tool that is used by web developers.

IT is also a very useful and frequently used tool for testing and controlling devices on the IOT and Home automation.

It is the http equivalent of the mosquitto_pub and mosquitto_sub tools for MQTT.

Recommended Reading

What every developer should know about urls

Resources

Using the command line-cURL–
Postman – an Google chrome extension
Rest Easy– An add-on for Firefox
Curl – Manual page

Related Tutorials:

Please rate? And use Comments to let me know more