Tutorial: Use the REST API#

This tutorial covers how to use the Abound API to access the scans that you have saved with the iOS SDK.

When you're finished, you'll have a Node.js script that downloads your scans.

You'll learn how to:

Authenticate your script with the Abound API.
Retrieve information about your scans.
Download top-down images of your scans.

Requirements#

Before starting, make sure you have completed the previous tutorial (Save and access scans) and have saved at least one scan.

Also, make sure you have Node.js installed.

This tutorial takes 10 minutes to complete.

Step 1: Create a Node.js package#

The Abound API can be accessed by any HTTP client. We'll be writing JavaScript to access it using Node.js.

Let's create a Node.js package so that we can install a dependency that will make HTTP requests easier.

Open Terminal and create a package by running the following commands.
```
mkdir ~/abound-tutorial
cd ~/abound-tutorial
npm init -y
```
Now, we'll install the axios HTTP client package along with support for persisting session with cookies. Run the following command in the directory you just created.
```
npm install axios axios-cookiejar-support tough-cookie
```

Step 2: Authenticate with the API#

Before using the Abound API, your app needs to be authenticated. We'll use the same API key that you generated for the iOS SDK.

It's not a good idea to include secret keys in code, so we'll store the key in an environment variable.

Open a text editor, and create a new file called fetch-scans.js in your package's directory (~/abound-tutorial).
Add the following code.

fetch-scans.js

const { default: axios } = require('axios');
const { CookieJar } = require('tough-cookie');
const { wrapper } = require('axios-cookiejar-support');

const client = wrapper(axios.create({
    baseURL: 'https://api.aboundlabs.com/v1/api',
    jar: new CookieJar(),
    withCredentials: true
}));

client
    .post('/authenticate', { apiKey: process.env.ABOUND_API_KEY })
    .then(resp => console.log(resp.data))
    .catch(err => console.error(err.toJSON()));

Open Terminal and run the following command to set an environment variable. Replace sk_your_api_key with your Abound API key (found on the Account page of the dashboard.)
```
export ABOUND_API_KEY=sk_your_api_key
```
Now, run the script with the following command.
```
node fetch-scans.js
```
You should see this output. If not, check that your API key is correct.
```
{ success: true, message: 'Successfully authenticated.' }
```

Step 3: Fetch your scan data#

Your API session is maintained using a cookie. This means later requests that use that cookie are authorized to access your app's data.

Let's make another request to retrieve information about the scans that have been made using your app.

Add the following code to your script.

fetch-scans.js

    // ...

    .then(resp => console.log(resp.data))
    .then(() => client.get('/scans'))
    .then(resp => {
        let scans = resp.data.data.scans;

        console.log('App has ' + scans.length + ' scans. The 3 most recent are:');
        const recentScans = scans.slice(0, 3);
        console.log(recentScans);
    })
    .catch(err => console.error(err.toJSON()));

Run the script again.
```
node fetch-scans.js
```

You should now see output similar to the following.

App has 8 scans. The 3 most recent are:
[ { uid: 'm8hbPtP',
    createdAt: '2022-06-03T02:02:16.436Z',
    tags: { description: 'Tompkins Square Park' },
    thumbnail:
     { url:
        'https://assets.aboundlabs.com/afs62oc/m8hbPtP/fw8ZTQt.jpeg',
       sizeBytes: 34809 },
    topDown:
     { url:
        'https://assets.aboundlabs.com/afs62oc/m8hbPtP/fKLqVX7.jpeg',
       sizeBytes: 47129 },
    obj:
     { url:
        'https://assets.aboundlabs.com/afs62oc/m8hbPtP/fUUG5Bb.obj.zip',
       sizeBytes: 344806 } },
  ...
]

Step 4: Download renderings#

When your user saves a scan, a top down image is rendered and stored. These renderings help you understand the layout of captured spaces.

The JSON returned by the API includes URLs for each of the scan's saved assets.

Let's add code to make your script download these images.

Edit your script to import the fs module so we're able to write to files.

fetch-scans.js

const { default: axios } = require('axios');
const { CookieJar } = require('tough-cookie');
const { wrapper } = require('axios-cookiejar-support');

const fs = require('fs');

const client = axios.create({
// ...

Next, add the following code to your script.

fetch-scans.js

        // ...

        console.log('App has ' + scans.length + ' scans. The 3 most recent are:');
        const recentScans = scans.slice(0, 3);
        console.log(recentScans);

        recentScans.forEach(scan => {
            if (scan.topDown) {
                axios.get(scan.topDown.url, { responseType: 'stream' }).then(response => {
                    const filename = scan.createdAt + '-' + scan.uid + '.jpeg';
                    console.log('Downloading ' + filename);
                    response.data.pipe(fs.createWriteStream(filename));
                });
            }
        });
    })
    .catch(err => console.error(err.toJSON()));

Run the script again.
```
node fetch-scans.js
```
The directory will now contain one image for each of your saved scans. To view these images on macOS, run the following command.
```
open *.jpeg
```

Next steps#

In this tutorial, you created a script that downloaded renderings of your scans.

To learn more about API functionality, read the API documentation.

Please send any feedback or suggestions to feedback@aboundlabs.com.