with cURL

A quick showcase of how cURL can be used to explore the various calls available on our REST API.

Overview

We will here show how cURL can be used to interact with our REST API. As an example, Basic Auth will be used to authenticate a GET request that fetches a list of available projects. All available endpoints are listed in our REST API Reference.

Prerequisites

• Enable Basic Auth You need to have created a Service Account with Basic Auth enabled. Any role will suffice.

cURL

cURL is a command-line tool that can be used to easily make arbitrary HTTP requests. This includes our entire API which can be accessed via a single cURL command. Detailed information about the parameters used can be found under cURLs manpage, man curl.

Installation

The tool comes preinstalled on most Linux and Mac systems. You can verify the install by opening your favorite shell and typing which curl , and are otherwise readily available in most package managers.

• Debian-based distributions: apt install curl

• Arch-based distributions: pacman -S curl

• Mac: brew install curl

• Windows: The cURL client binary can be found here.

GET Request

The following command will fetch a list of all available projects for a Service Account.

curl -X GET "https://api.disruptive-technologies.com/v2/projects" \
    -u "<YOUR_SERVICE_ACCOUNT_KEY_ID>":"<YOUR_SERVICE_ACCOUNT_SECRET>"

• -X <command> Specifies the HTTP request method and to which URL it is sent. The method, usually GET or POST, should be changed to accommodate the target URL.

• -u <user:password> Specifies the user for authentication. We use a Service Account, and the key-id and secret can be found when creating the account, as explained in the Basics of Service Accounts.

If the valid key-id and secret of a Service Account with sufficient privileges were used, cURL should return a list of the available projects for that account to stdout.

{"projects":[{"name":"projects/btadoe94jplfdvvdr6q0","displayName":"wCaV7Y",
"organization":"organizations/b9spme0i0da0037ge49g","organizationDisplayName":
"Disruptive Technologies Research","sensorCount":10,"cloudConnectorCount":1,
"inventory":false}],"nextPageToken":""}

POST Request

The following command adds the label my-new-label with value some-value to the specified device.

curl -X POST "https://api.d21s.com/v2/projects/<YOUR_PROJECT_ID>/devices/<YOUR_DEVICE_ID>/labels" \
    -u "<YOUR_SERVICE_ACCOUNT_KEY_ID>":"<YOUR_SERVICE_ACCOUNT_SECRET>" \
    -d '{"key": "my-new-label", "value": "some-value"}'

• -X <command> Specifies the HTTP request method and to which URL it is sent. The method, usually GET or POST, should be changed to accommodate the target URL.

• -u <user:password> Specifies the user for authentication. We use a Service Account, and the key-id and secret can be found when creating the account, as explained in the Basics of Service Accounts.

• -d <data> Sends the specified data in a POST request to the HTTP server.

If the valid key-id and secret of a Service Account with sufficient privileges were used, cURL should return a list of the available projects for that account to stdout.

{
  "name": "projects/<YOUR_PROJECT_ID>/devices/<YOUR_DEVICE_ID>/labels/my-new-label",
  "key": "my-new-label",
  "value": "some-value"
}

Optional Formatting

cURL alone makes no attempt at formatting its output. By piping the cURL output through a command-line JSON processor like jq, the result is much more readable.

curl <insert-command-here> | jq

The same response as previously now looks like the following.

{
  "projects": [
    {
      "name": "projects/btadoe94jplfdvvdr6q0",
      "displayName": "wCaV7Y",
      "organization": "organizations/b9spme0i0da0037ge49g",
      "organizationDisplayName": "Disruptive Technologies Research",
      "sensorCount": 10,
      "cloudConnectorCount": 1,
      "inventory": false
    }
  ],
  "nextPageToken": ""
}