# Getting Started

## 1. Get API Client ID and Secret

To access the DAP API, you will need a Client ID and Secret. These are generated via the Instructure Identity Services.

#### Steps:

1. Log into [Instructure Identity Services](https://identity.instructure.com).
2. Select your institution from the drop-down menu and log in.
3. Once authorized, navigate to the dashboard and click **Add New Key**.
4. Enter a name for the key and set the expiration time.
5. Copy the **Client ID** and **Secret** when they appear. **Note:** These are displayed only once. If you lose them, you will need to generate new ones.

## 2. Install DAP CLI on Your Computer

The DAP CLI tool allows you to interact with the Canvas Data 2 API. Installation steps differ slightly depending on your operating system.

#### For Mac:

1. Install Xcode Developer Tools:

   ```sh
   xcode-select --install
   ```
2. download and install Python 3.10+ from [here](https://www.python.org/downloads/):

   ```sh
   python3 --version
   ```
3. Install PIP (if not installed by default):

   ```sh
   pip3 --version
   ```
4. Install the DAP CLI tool with PostgreSQL support:

   ```sh
   pip3 install "instructure-dap-client[postgresql]"
   ```

#### For Windows:

1. Install Python 3.10+ from [here](https://www.python.org/downloads/windows/).
2. Install the DAP CLI tool using the Windows command prompt:

   ```sh
   pip3 install "instructure-dap-client[postgresql]"
   ```

If you miss installing an extra feature, the library will not be able to synchronize data with a database, and you may get an error message similar to the following:

```bash
ERROR - missing dependency: `asyncpg`; you may need to run `pip install pysqlsync[postgresql]`
```

## 3. Store Client Credentials in Environment Variables

For secure access to the API, it's recommended to store your credentials as environment variables. This prevents sensitive information from being exposed in command-line arguments.

#### MacOS/Linux:

1. Open Terminal and run the following commands, replacing placeholders with your actual Client ID and Secret:

   ```sh
   export DAP_API_URL='https://api-gateway.instructure.com'
   export DAP_CLIENT_ID='your_canvas_data_client_id'
   export DAP_CLIENT_SECRET='your_canvas_data_secret'
   ```
2. Restart Terminal for changes to take effect.

#### Windows:

Follow this [guide to setting environment variables](https://www.computerhope.com/issues/ch000549.htm) or use the `set` command in the Windows command line:

```sh
set DAP_API_URL=https://api-gateway.instructure.com
set DAP_CLIENT_ID=your_canvas_data_client_id
set DAP_CLIENT_SECRET=your_canvas_data_secret
```

## 4. Work with Databases

DAP CLI allows you to interact with PostgreSQL or MySQL databases. You will need the connection string of your database for DAP to function correctly.

#### Connection String Format:

```
protocol://username:password@host:port/database_name
```

#### Example for PostgreSQL:

```
postgresql://user:password@localhost:5432/mydatabase
```

### Store Connection String in Environment Variables

#### MacOS/Linux:

1. Open Terminal and run the following commands, replacing placeholders with your actual Client ID and Secret:

   ```sh
   export DAP_CONNECTION_STRING=postgresql://user:password@localhost:5432/mydatabase
   ```
2. Restart Terminal for changes to take effect.

#### Windows:

Follow this [guide to setting environment variables](https://www.computerhope.com/issues/ch000549.htm) or use the `set` command in the Windows command line:

```sh
set DAP_CONNECTION_STRING=postgresql://user:password@localhost:5432/mydatabase
```

### Obtain a Full Snapshot of a Table

Use the [`dap initdb`](https://p0kk-co.gitbook.io/playground/) command to download a full snapshot of a table and store it in your database.

#### Command:

```sh
dap initdb --connection-string postgresql://user:password@localhost/mydb --namespace canvas --table accounts
```

{% hint style="warning" %}
Regular use of snapshots is not recommended, as they are resource-intensive for the API and costly to process on the client side.
{% endhint %}

### Synchronize Data with a Table

After obtaining a snapshot, keep your database updated with the [`dap syncdb`](https://p0kk-co.gitbook.io/playground/) command. This ensures incremental changes are applied to your table.

#### Command:

```sh
dap syncdb --connection-string postgresql://user:password@localhost/mydb --namespace canvas --table accounts
```

### Changing the Temporary Storage Location

If you need to change the temporary storage directory for data processing, you can configure the location using the following command-line option:

```sh
dap syncdb --temp-dir /new/temp/location --connection-string postgresql://user:password@localhost/mydb --namespace canvas --table accounts
```

## 5. Export Data

You can export data using either the snapshot or incremental methods, depending on your use case.

### Snapshot Export

Use [`dap snapshot`](https://p0kk-co.gitbook.io/playground/) command to download a full copy of a table at a point in time.

#### Command:

```sh
dap snapshot --namespace canvas --table accounts
```

{% hint style="warning" %}
Regular use of snapshots is not recommended, as they are resource-intensive for the API and costly to process on the client side.
{% endhint %}

### Incremental Export

The [`dap incremental`](https://p0kk-co.gitbook.io/playground/) commands captures only the data that has changed since your last export.

#### Command:

```sh
dap incremental --namespace canvas --table accounts --since YYYY-MM-DDTHH:MM:SSZ
```

## Related Resources

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Key Concepts</strong></td><td>Get familiar with the concepts in DAP.</td><td><a href="/spaces/md43XhVX1tvwrv25xyTO">/spaces/md43XhVX1tvwrv25xyTO</a></td></tr><tr><td><strong>Rate Limits &#x26; Policies</strong></td><td>Learn more about the limits and our policies.</td><td><a href="/spaces/md43XhVX1tvwrv25xyTO">/spaces/md43XhVX1tvwrv25xyTO</a></td></tr><tr><td><strong>Datasets</strong></td><td>Discover namespaces and available tables</td><td><a href="/spaces/md43XhVX1tvwrv25xyTO">/spaces/md43XhVX1tvwrv25xyTO</a></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://p0kk-co.gitbook.io/playground/readme/getting-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.