> For the complete documentation index, see [llms.txt](https://p0kk-co.gitbook.io/playground/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://p0kk-co.gitbook.io/playground/readme/getting-started.md). # 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
Key ConceptsGet familiar with the concepts in DAP./spaces/md43XhVX1tvwrv25xyTO
Rate Limits & PoliciesLearn more about the limits and our policies./spaces/md43XhVX1tvwrv25xyTO
DatasetsDiscover namespaces and available tables/spaces/md43XhVX1tvwrv25xyTO