Skip to content

Quickstart

This guide will show you how to get the Hotswap widget working on your site.

Step 1: Create a new migration (Server)

On your server, make a call to the /api/sessions endpoint.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import requests

data = {
    'api_key': 'HOTSWAP API KEY'
}

rc = requests.post(
    'https://widget.hotswap.app/api/sessions',
    json=data
).json()

token = rc['token']

Bootstrap Widget with Session Configurations (Optional)

If you want to launch the widget with a specific configuration, you can do that in a single API call. For example, to create a session with the destination pre-configured, you can do the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import requests

data = {
    'api_key': 'HOTSWAP API KEY',
    'destination': {
        'platform': 'github',
        'params': {
            'api_key': '{YOUR_GITHUB_API_KEY}',
        }
    }
}

rc = requests.post(
    'https://widget.hotswap.app/api/sessions',
    json=data
).json()

token = rc['token']

Webhooks (Optional)

You may provide a webhook URL which we will call when a migration has completed.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import requests

data = {
    'api_key': 'HOTSWAP API KEY',
    'webhook_url': 'https://example.com/',
}

rc = requests.post(
    'https://widget.hotswap.app/api/sessions',
    json=data
).json()

token = rc['token']

Our server will make a POST request with the following payload:

1
2
3
4
{
  "session_id": "session-id-string",
  "progress": "SUCCESS"
}

The progress key can have a value of SUCCESS or FAILURE.

Step 2: Create Widget on your Site (Client)

Once you have the token, you can use that to create the widget on your site. You just need to instantiate the Hotswap object and call Hotswap.open().

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
<html>
    <head>
        <script src="https://widget.hotswap.app/js/hotswap.js"></script>
    </head>
    <body>

        <button type="button" onClick="hotswap.open()">
            Click here to migrate
        </button>

        <script type="text/javascript">
            hotswap = Hotswap({
                // Replace with session token generated on server
                token: '{SESSION TOKEN}'
            });
        </script>

    </body>
</html>

Widget closed callback (Optional)

You may provide an onClose callback which is triggered when the widget is closed.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
<html>
    <head>
        <script src="https://widget.hotswap.app/js/hotswap.js"></script>
    </head>
    <body>

        <button type="button" onClick="hotswap.open()">
            Click here to migrate
        </button>

        <script type="text/javascript">
            hotswap = Hotswap({
                // Replace with session token generated on server
                token: '{SESSION TOKEN}',
                onClose() {
                    // The widget has been closed
                }
            });
        </script>

    </body>
</html>

Start the migration via API

If you want to "kick off" the migration on your server, rather than using our widget, you may make a POST request to /api/sessions/<session_token>/start This is the value provided in the token variable when creating the migration session.

1
2
3
import requests

rc = requests.post('https://widget.hotswap.app/api/sessions/<session_token>/start')

Full example

On Github, we have a full example application written with Python + Flask.