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
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:
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.
Tip: For a GET request you can also use a 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:
- IOT API’s For beginners
- HTTP API’s for IOT
- Creating an IOT or MQTT Dashboard Using Thingsboard
- Introduction to HTTP : Understanding HTTP Basics