MovingLake Docs
Connectors Destinations API Documentation Security movinglake.com
MovingLake Docs

API Documentation

MovingLake's new V2 API

MovingLake - Partners API

Contents

Introduction
Terminology
Usage Guidelines

Introduction

The following document gives a general overview of the API Endpoints required for the collaboration between MovingLake and its partners. We’ll begin with an overview of all relevant terminology, followed by recommendations and guidelines on how to use the API. Finally we’ll provide an individual description of every endpoint.

Terminology

MovingLake provides a way to connect data from point A to point B. The API provides a way to create, describe and manage these connections, so there are several key terms that will show up repeatedly so we’ll clarify them first.

  1. Source: This is where we get data from. For example, a database or an API.
  2. Destination: This is where we write or submit data. This can be an HTTP Endpoint or a database.
  3. Entity: Sources provide different types of data. For example, an integration to a PMS provides data such as listings and reservations. These would be the entities. Importantly, in every connector, entities can be configured to run at different intervals, or can be individually deactivated depending on the destination.
  4. Connector: It is the instance of a single source, to one or more destinations. For example, a connector is the entity that moves the data from a PMS into a specific database. Since the connector is tied to a single source, sometimes source and connector are used interchangeably in the API for compatibility reasons.
  5. Source Template: This is the canonical representation of a given source. For example, you can create several connectors to different MySQL databases as sources, but the MySQL Source template describes how a MySQL source looks (i.e. which parameters it requires and which entities it provides).
  6. Connector Template: Alias for Source Template for compatibility reasons.
  7. Destination Template: Similar to the source template, it describes the parameters required by a destination of its type. For example, an HTTP destination requires a URL for posting the data.

Usage Guidelines

The API uses OAuth for authentication. You will be provided by your account manager an API Key and API Secret which you must store securely. Note: MovingLake is in the process of developing an API Key management module so you can securely handle the lifecycle of your keys.

General Considerations

MovingLake API uses JSON as its only data type. All requests must be authenticated and always use HTTPS (HTTP will simply redirect you to HTTPS) and never omit the SSL verification if there’s ever a problem with the certificate.

Also, except for authentication, all requests have the prefix /api/v2 . While most of these operations reflect actions that you can take from MovingLake’s UI, using the API not under /api/v2 is not officially supported nor recommended. If you require more data or a new endpoint please contact your MovingLake Account Manager.

Authentication

In order to create a token for your subsequent requests, you can do an HTTP request with your API key and API secret using Basic HTTP Authentication. (Note that while Basic HTTP Authentication is supported by almost every HTTP Client, it is easy to implement it yourself. See the

# These assumes API Key and API Token are in environment variables
curl -u "$API_KEY:$API_SECRET" \
  -h 'Cache-Control: no-cache' \
  -h 'Content-Type: application/json' \
  -d '{"grant_type": "client_credentials"}' \
  -X POST \
	https://connector.production.movinglake.com/o/token/

This will return a JSON object that contains the access_token key. Like the following:

{
    "access_token": "example_token"
}

This token will eventually expire and you can simply re-authenticate using the method above. If you make an unauthenticated request or the token expires you will get a 401 or 403 status response.

Example of an Authenticated Request

You can use the token that you got from the previous section like this:

curl -h 'Content-Type: application/json' \
     -h "Authorization: Bearer $ACCESS_TOKEN" \
     https://connector.production.movinglake.com/api/v2/connector-templates

List of endpoints

I - Catalogues

These endpoints provide data for the available templates provided by MovingLake (see Terminology for more details).

I.I List available connector templates

Endpoint /api/v2/connector-templates/
Method GET
Query parameters category - a string containing the category for the connector (example, PMS)
Example Request GET /api/v2/connector-templates/?category=PMS
Notes If you don’t provide a category you will get all available templates. A wrong category filter will result on an empty list.

MovingLake_-_Partners_API.pdf

Example Response

[
		{
        "id": 43,
        "code": "airbnb",
        "name": "Airbnb",
        "description": "Airbnb Connector",
        "icon": "/media/icons/cat_connectors/airbnb.png",
        "country_code": "",
        "connector_categories": [
            {
                "id": 6,
                "name": "Hospitality"
            }
        ]
    },
    {
        "id": 46,
        "code": "guesty_enterprise",
        "name": "Guesty Enterprise",
        "description": "Guesty PMS connector for enterprises",
        "icon": "/media/icons/cat_connectors/guesty-v2.jpeg",
        "country_code": null,
        "connector_categories": [
            {
                "id": 6,
                "name": "Hospitality"
            },
            {
                "id": 19,
                "name": "PMS"
            }
        ]
    }
]

I.II Get the Details for a Specific Connector Template

Endpoint /api/v2/connector-templates/:template_id
Method GET
Query parameters None
Example Request GET /api/v2/connector-templates/46
Notes There are three principal components here: general connector data, the credentials and the entities.

Of particular importance is the credentials key, since it provides information on how to render the form for the given connector.

The entities key lists all available entities and the available update frequencies for each one of them. |

Example Response

{
    "connector": {
        "id": 46,
        "code": "guesty_enterprise",
        "name": "Guesty Enterprise",
        "description": "Guesty PMS connector for enterprises",
        "icon": "/media/icons/cat_connectors/guesty-v2.jpeg",
        "country_code": null,
        "connector_categories": [
            {
                "id": 6,
                "name": "Hospitality"
            },
            {
                "id": 19,
                "name": "PMS"
            }
        ]
    },
    "credentials": {
        "schema_form": [
            {
                "id": "integration_token",
                "type": "INPUT",
                "label": "Integration Token",
                "required": true,
                "placeholder": "Enter your Integration Token",
                "autoComplete:": "off"
            }
        ]
    },
    "entities": [
        {
            "id": 282,
            "name": "guesty_reservations",
            "description": "",
            "entity_timer": [
                {
                    "id": 3,
                    "name": "Every 5 minutes",
                    "repeat_every": 300
                },
                {
                    "id": 4,
                    "name": "Every 10 minutes",
                    "repeat_every": 600
                }
             
            ]
        },
      
        {
            "id": 289,
            "name": "guesty_listing",
            "description": "",
            "entity_timer": [
                {
                    "id": 3,
                    "name": "Every 5 minutes",
                    "repeat_every": 300
                },
                {
                    "id": 4,
                    "name": "Every 10 minutes",
                    "repeat_every": 600
                }
            ]
        }
    ]
}

I.III List available destination templates

Endpoint /api/v2/destination-templates/
Method GET
Query parameters None
Example Request GET /api/v2/destination-templates/

Example Response

[
    {
        "id": 2,
        "code": "bigquery",
        "name": "BigQuery",
        "description": "google database",
        "icon": "/media/icons/adapters/bigquery.png"
    },
    {
        "id": 3,
        "code": "snowflake",
        "name": "Snowflake",
        "description": "Database in the cloud",
        "icon": "/media/icons/adapters/snowflake.png"
    }
]

I.IV Get the Details for a Specific Destination Template

Endpoint /api/v2/destination-templates/:template_id
Method GET
Query parameters None
Example Request GET /api/v2/destination-templates/2
Notes Similar to the connector template detail, this endpoint provides the schema_form key which contains the description on how to render the form for the destination.

Example Response

{
    "id": 2,
    "code": "bigquery",
    "name": "BigQuery",
    "description": "google database",
    "scheme_form": {
        "layout": {},
        "schema_form": [
            {
                "id": "bq_dataset",
                "type": "INPUT",
                "label": "Dataset",
                "required": true,
                "placeholder": "Enter your dataset"
            },
            {
                "id": "destination_project_id",
                "type": "INPUT",
                "label": "Destination project id",
                "required": true,
                "placeholder": "Enter project id"
            },
            {
                "id": "credential",
                "type": "INPUT",
                "label": "Credential JSON (optional)",
                "required": false,
                "placeholder": "Paste here"
            }
        ]
    },
    "icon": "/media/icons/adapters/bigquery.png",
    "is_active": true,
    "created_at": "2022-06-25T22:32:33.971000Z",
    "updated_at": "2022-08-08T03:39:39.594000Z"
}

II - Organization Resources

These endpoints get and create resources within the scope of the current organization account. This means, within the owner of the API Keys. If you create connector on behalf of your customers, everything is kept within your organization anyway.

II.I List Organization Destinations

Endpoint /api/v2/destinations/
Method GET
Query parameters None
Example Request GET /api/v2/destinations/

Example Response

[
    {
        "id": 1,
        "organization": 2,
        "name": "My Google Sheets Destination",
        "type_adapter_name": "Google Sheets",
        "icon": "icons/adapters/sheets.png"
    }
]

II.II Create a New Destination

Endpoint /api/v2/destinations/
Method POST
Query parameters None
Example Request POST /api/v2/destinations/
Notes The relevant parameters are inside the credential_json key in the in the request body. Those will vary depending on the the type of destination (the type_adapter key, which corresponds to the ID of the /api/v2/destination-templates response).

Note that if you are going to use a single destination for all of your customers, it is recommended to create the destination from MovingLake UI and use the previous endpoint for choosing the right ID. |

Example Body

{
    "name": "Test destination",
    "credential_json": {
        "sheet-url": "www.test.com",
        "cleanup": true,
        "oauth-complete": true
    },
    "type_adapter": 7
}

Example Response

{
    "id": 2,
    "type_adapter_name": "Google Sheets",
    "name": "Test destination",
    "credential_json": {
        "sheet-url": "www.test.com",
        "cleanup": true,
        "oauth-complete": true
    },
    "created_at": "2023-02-16T00:18:25.009907Z",
    "updated_at": "2023-02-16T00:18:25.009920Z",
    "type_adapter": 7,
    "user": 3,
    "organization": 3
}

II.III Update an Existing Destination

Endpoint /api/v2/destinations/:destination_id
Method PUT
Query parameters None
Example Request PUT /api/v2/destinations/3
Notes Following REST conventions, a full representation of the resource should be provided.

Example Body

{
    "name": "Test destination",
    "credential_json": {
        "sheet-url": "www.changed-value.com",
        "cleanup": true,
        "oauth-complete": true
    },
    "type_adapter": 7
}

Example Response

{
    "name": "Test destination",
    "credential_json": {
        "sheet-url": "www.changed-value.com",
        "cleanup": true,
        "oauth-complete": true
    },
    "type_adapter": 7
}

II.IV List Organization Connectors

Endpoint /api/v2/connectors/
Method GET
Query parameters None
Example Request GET /api/v2/connectors/

Example Response

[
    {
        "id": 1,
        "name": "Test connector",
        "description": "",
        "lifecycle_status": "CREATION_STARTED",
        "is_active": true,
        "connector_cat": 1,
        "connector_cat_name": "Amazon Ads",
        "icon": "icons/cat_connectors/amazon_ads.png"
    }
]

II.V Create a New Connector

Endpoint /api/v2/connectors/
Method POST
Query parameters None
Example Request POST /api/v2/connectors/
Notes Note that the credentials are taken from the templates form. Because it is assumed to be user input, all values in the credentials key are assumed to be strings.

The targets section is the one that actually ties the source to the destination, and for every destination you can configure the entity frequency or whether or not to keep it active. |

Example Body

{
    "name": "Test connector",
    "connector_category_id": 46,
    "credentials": {
        "integration_token": "test_token"
    },
    "targets": [
        {
            "destination_id": 4,
            "entities": [
                {
                    "id": 281,
                    "entity_timer_id": 3,
                    "is_active": true
                }
            ]
        }
    ]
}

Example Response

{
    "success": true,
    "data": {
        "id": 2,
        "name": "Test connector",
        "description": "",
        "lifecycle_status": "CREATION_STARTED",
        "is_active": true,
        "connector_cat": 46,
        "connector_cat_name": "Guesty Enterprise",
        "icon": "icons/cat_connectors/guesty-v2.jpeg"
    }
}

Example Response

{
    "success": true,
    "data": {
        "id": 2,
        "name": "Test connector",
        "description": "",
        "lifecycle_status": "CREATION_STARTED",
        "is_active": true,
        "connector_cat": 46,
        "connector_cat_name": "Guesty Enterprise",
        "icon": "icons/cat_connectors/guesty-v2.jpeg"
    }
}