Using the CURL Command

This section demonstrates the use of the curl command to interact with a RESTful API to request resources. The API response is in JSON format.

The curl utility is a command-line tool available on Unix, Linux, Mac OS, X Windows, and many other platforms. This utility provides easy direct access to the HTTP protocol from the command-line and is therefore an ideal way to interact with ThingsPro via the HTTP RESTful API.

Using mx-api-token

Refer to Get API Token for details on acquiring a mx-api-token

Usage: Include the mx-api-token token in the header and specify the --insecure option to skip certificate validation. For simple GET requests use the following:

$ curl --insecure -H 'mx-api-token: <token>' \
       [-X GET] https://localhost/api/v1/<resource>

For PUT, POST or DELETE request for JSON data, use the following:

$ curl --insecure -H 'mx-api-token: <token>' \
       -H 'Content-Type: application/json' \
       -X <POST|PUT|DELETE> https://localhost/api/v1/<resource> \
       -d '<DATA>'

Getting a Resource

Usage: For simple GET requests, just provide the URL of the request in the -X GET command. The -X GET command specifies the GET option, which is the default operation of the curl command.

$ curl --insecure -H 'mx-api-token: <token>' \
       [-X GET] https://localhost/api/v1/<resource>

Example of a GET Request

The following example requests the first port mapping rule:

$ curl --insecure -H 'mx-api-token: <token>' \
       https://localhost/api/v1/network/portmapping/1

The response from the port mapping resource in JSON format is given below:

{
  "id": 1,
  "enable": true,
  "service": "http",
  "portStart": 80,
  "portEnd": 80,
  "destIp": "192.168.5.123",
  "protocol": "tcp"
}

Some resources provide a collection of content as in the following case:

$ curl --insecure -H 'mx-api-token: <token>' \
       https://localhost/api/v1/network/portmapping

[
  {
    "id": 1,
    "enable": true,
    "service": "http",
    "portStart": 80,
    "portEnd": 80,
    "destIp": "192.168.5.123",
    "protocol": "tcp"
  },
  {
    "id": 2,
    "enable": false,
    "service": "test",
    "portStart": 12340,
    "portEnd": 12345,
    "destIp": "192.168.5.123",
    "protocol": "both"
  }
]

Creating/Updating a Resource

Usage: Specify a header using the -H option and provide data using the -d option.

$ curl --insecure -H 'mx-api-token: <token>' \
       -H 'Content-Type: application/json' \
       -X <POST|PUT> https://localhost/api/v1/<resource> \
       -d '<DATA>'

Example of a POST Request

The following command creates a port mapping rule using the curl command:

$ curl --insecure -H 'mx-api-token: <token>' \
       -H 'Content-Type: application/json' \
       -X POST https://localhost/api/v1/network/portmapping \
       -d '{ "enable": true,
             "service": "http",
             "portStart": 8080,
             "portEnd": 8080,
             "destIp": "192.168.5.123",
             "protocol": "tcp"}'

After the create (POST) command is processed, an id is assigned and included in the JSON response.

{
  "id": 2,
  "enable": true,
  "service": "http",
  "portStart": 8080,
  "portEnd": 8080,
  "destIp": "192.168.5.123",
  "protocol": "tcp"
}

Example of a PUT Request

The following command requests an update to the second port mapping rule:

$ curl --insecure -H 'mx-api-token: <token>' \
       -H 'Content-Type: application/json' \
       -X PUT https://localhost/api/v1/network/portmapping/2 \
       -d '{ "id": 2,
             "enable": true,
             "service": "http",
             "portStart": 8000,
             "portEnd": 8000,
             "destIp": "192.168.5.123",
             "protocol": "tcp"}'

The response to the PUT request is as shown below:

{
  "id": 2,
  "enable": true,
  "service": "http",
  "portStart": 8000,
  "portEnd": 8000,
  "destIp": "192.168.5.123",
  "protocol": "tcp"
}

Deleting a Resource

Usage: Specify the URL of the resource that you want to delete.

$ curl --insecure -H 'mx-api-token: <token>' \
       -X DELETE https://localhost/api/v1/<resource>

Example of a DELETE Request

To delete a port mapping rule with id = 2, use the following command:

$ curl --insecure -H 'mx-api-token: <token>' \
       -X DELETE https://localhost/api/v1/network/portmapping/2