# with cURL

## 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](https://developer.disruptive-technologies.com/api).

## Prerequisites

* **Enable Basic Auth**\
  You need to have [created a Service Account](https://docs.developer.disruptive-technologies.com/service-accounts/creating-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](https://curl.haxx.se/download.html#Win64).

## GET Request

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

```bash
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](https://docs.developer.disruptive-technologies.com/service-accounts/introduction-to-service-accounts).&#x20;

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.

```javascript
{"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.

```bash
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](https://docs.developer.disruptive-technologies.com/service-accounts/introduction-to-service-accounts).&#x20;
* **-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.

```javascript
{
  "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](https://stedolan.github.io/jq/),  the result is much more readable.&#x20;

```bash
curl <insert-command-here> | jq
```

The same response as previously now looks like the following.

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