Fivetran API Examples to build custom connectors

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for fivetrandevelopers from gravatar.com fivetrandevelopers Avatar for fivetran-satvik from gravatar.com fivetran-satvik Avatar for rishabh.ghosh from gravatar.com rishabh.ghosh Avatar for varun-fivetran from gravatar.com varun-fivetran
Meta

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License
  • Requires: Python >=3.10
Classifiers
Report project as malware

Project description

Fivetran API Playground

Downloads

The Fivetran API Playground enables you to explore various sample API endpoints on your local machine, helping you better understand the complexities of real-world APIs. It serves as a hands-on learning tool for building connectors, allowing you to write custom Python code within Fivetran's secure cloud environment. For more information, see our Connector SDK documentation.

Install

pip install fivetran-api-playground

Requirements

  • Python ≥3.10 and ≤3.12
  • Operating System:
    • Windows 10 or later
    • MacOS 13 (Ventura) or later
    • Linux: Distributions such as Ubuntu 20.04 or later, Debian 10 or later, or Amazon Linux 2 or later

Usage

To start the API, run the following command:

playground start  # starts the server on 5001 port by default

playground start --port 
# starts the server on the specified port

You will see a message like:

Starting Local API on port 5001 ...
--------------------------------------------------------------------------------------------------------------------------------------------
Pagination Type                | Endpoint                                          
--------------------------------------------------------------------------------------------------------------------------------------------
Next Page URL Pagination       | GET http://127.0.0.1:5001/pagination/next_page_url
Page Number Pagination         | GET http://127.0.0.1:5001/pagination/page_number  
Offset Pagination              | GET http://127.0.0.1:5001/pagination/offset       
Keyset Pagination              | GET http://127.0.0.1:5001/pagination/keyset       
--------------------------------------------------------------------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------------------------------------------------------
API Endpoint Type              | Endpoint                                          
--------------------------------------------------------------------------------------------------------------------------------------------
Export with CSV                | GET http://127.0.0.1:5001/export/csv              
--------------------------------------------------------------------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------------------------------------------------------
Incremental Sync Type          | Endpoint                                          
--------------------------------------------------------------------------------------------------------------------------------------------
Timestamp Incremental Sync     | GET http://127.0.0.1:5001/incremental/timestamp   
Step-size Incremental Sync     | GET http://127.0.0.1:5001/incremental/step        
--------------------------------------------------------------------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------------------------------------------------------
Authentication Endpoint Type   | Endpoint                                           | Credentials                                       
--------------------------------------------------------------------------------------------------------------------------------------------
Http Basic Auth                | GET http://127.0.0.1:5001/auth/http_basic          | Username: 4779a@example.com Password: 673727a8    
HTTP Bearer                    | GET http://127.0.0.1:5001/auth/http_bearer         | Bearer Token: 69574aad-4d3f-4fb5-9903-caba56ad9de1
Auth API Key                   | GET http://127.0.0.1:5001/auth/api_key             | API Key: 3e4cdf4d-f81c-4ee8-8218-3fd0cb22aeae     
Session Token Auth Login       | GET http://127.0.0.1:5001/auth/session_token/login | Username: e7ccb@example.com  Password: 3c89b9bb2a 
Session Token Auth Data        | GET http://127.0.0.1:5001/auth/session_token/data  | Use Token Received from Login endpoint  
--------------------------------------------------------------------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------------------------------------------------------
Cursor Endpoint Type           | Endpoint                                          
--------------------------------------------------------------------------------------------------------------------------------------------
Companies Cursor               | GET http://127.0.0.1:5001/cursors/companies       
Departments by Company Cursor  | GET http://127.0.0.1:5001/cursors/<company_id>/departments          
--------------------------------------------------------------------------------------------------------------------------------------------
You can read about the API documentation for each endpoint on: 
https://pypi.org/project/fivetran-api-playground/
--------------------------------------------------------------------------------------------------------------------------------------------
For your observability the API requests will be logged here!
Keep this process up and running until you finish trying out the API.

Press CTRL+C to quit

API Endpoints

There are four types of pagination available, allowing you to fetch up to 200 dynamically-generated records with dummy data each time the server is run locally using the playground start command.

1. Next Page URL Pagination

  • Endpoint: /pagination/next_page_url
  • Method: GET
  • Query Parameters:
    Parameter Type Required Description
    order_by string No Parameter to order by. Allowed values: createdAt, updatedAt. Default: updatedAt.
    order_type string No Sorting order. Allowed values: asc, desc. Default: asc.
    per_page integer No Number of items per page (1-50). Default: 10.
    updated_since string No Return items updated since this timestamp. Format: YYYY-MM-DDTHH:MM:SSZ.
  • Response:
    • data: Array of items for the current page.
    • total_items: Total number of items after filtering.
    • page: Current page number.
    • per_page: Number of items per page.
    • next_page_url: URL for the next page, if available.
  • Sample Request: 
    curl -X GET http://127.0.0.1:5001/pagination/next_page_url
  • Sample Response: 
    {
  "data": [
    {
      "id": "1989d8f6-57a5-41bf-b21b-4d6de6db6de6",
      "name": "XYZ",
      "email": "xyz@example.net",
      "address": "Some Random Address, AS 18073",
      "company": "Nguyen, Nash and King",
      "job": "Licensed conveyancer",
      "createdAt": "2024-09-22T12:15:33Z",
      "updatedAt": "2024-09-22T12:15:50Z"
    },
    ...
  ],
  "total_items": 200,
  "page": 1,
  "per_page": 10,
  "next_page_url": "http://127.0.0.1:5001/pagination/next_page_url?page=2&per_page=10&order_by=updatedAt&order_type=asc"
}

2. PAGE Number Pagination

  • Endpoint: /pagination/page_number
  • Method: GET
  • Query Parameters:
    Parameter Type Required Description
    order_by string No Parameter to order by. Allowed values: createdAt, updatedAt. Default: updatedAt.
    order_type string No Sorting order. Allowed values: asc, desc. Default: asc.
    per_page integer No Number of items per page (1-50). Default: 10.
    page integer No Page number to retrieve (1 or higher). Default: 1.
    updated_since string No Return items updated since this timestamp. Format: YYYY-MM-DDTHH:MM:SSZ.
  • Response:
    • data: Array of items for the current page.
    • page: Current page number.
    • page_size: Number of items per page.
    • total_pages: Total number of pages.
    • total_items: Total number of items.
  • Sample Request: 
    curl -X GET http://127.0.0.1:5001/pagination/page_number
  • Sample Response: 
    {
  "data": [
    {
      "id": "1989d8f6-57a5-41bf-b21b-4d6de6db6de6",
      "name": "XYZ",
      "email": "xyz@example.net",
      "address": "Some Random Address, AS 18073",
      "company": "Nguyen, Nash and King",
      "job": "Licensed conveyancer",
      "createdAt": "2024-09-22T12:15:33Z",
      "updatedAt": "2024-09-22T12:15:50Z"
    },
    ...
  ],
  "page": 1,
  "page_size": 10,
  "total_pages": 20,
  "total_items": 200
}

3. Offset Pagination

  • Endpoint: /pagination/offset
  • Method: GET
  • Query Parameters:
    Parameter Type Required Description
    order_by string No Parameter to order by. Allowed values: createdAt, updatedAt. Default: updatedAt.
    order_type string No Sorting order. Allowed values: asc, desc. Default: asc.
    limit integer No Number of items to return (1-50). Default: 10.
    offset integer No Number of items to skip before starting to collect the result set. Default: 0.
    updated_since string No Return items updated since this timestamp. Format: YYYY-MM-DDTHH:MM:SSZ.
  • Response:
    • data: Array of items retrieved based on limit and offset.
    • offset: The offset used in the request.
    • limit: The limit used in the request.
    • total: Total number of items after filtering.
  • Sample Request: 
    curl -X GET http://127.0.0.1:5001/pagination/offset
  • Sample Response: 
    {
  "data": [
    {
      "id": "1989d8f6-57a5-41bf-b21b-4d6de6db6de6",
      "name": "XYZ",
      "email": "xyz@example.net",
      "address": "Some Random Address, AS 18073",
      "company": "Nguyen, Nash and King",
      "job": "Licensed conveyancer",
      "createdAt": "2024-09-22T12:15:33Z",
      "updatedAt": "2024-09-22T12:15:50Z"
    },
    ...
  ],
  "offset": 0,
  "limit": 10,
  "total": 200
}

4. Keyset Pagination

  • Endpoint: /pagination/keyset
  • Method: GET
  • Query Parameters:
    Parameter Type Required Description
    scroll_param string No Base64 encoded timestamp to fetch items after this timestamp.
    updated_since string No Return items updated since this timestamp. Format: YYYY-MM-DDTHH:MM:SSZ.
  • Response:
    • data: Array of items retrieved based on keyset pagination.
    • total_count: Total number of items after filtering.
    • scroll_param: Base64 encoded parameter for the next page, if available.
  • Sample Request: 
    curl -X GET http://127.0.0.1:5001/pagination/keyset
  • Sample Response: 
    {
  "data": [
    {
      "id": "1989d8f6-57a5-41bf-b21b-4d6de6db6de6",
      "name": "XYZ",
      "email": "xyz@example.net",
      "address": "Some Random Address, AS 18073",
      "company": "Nguyen, Nash and King",
      "job": "Licensed conveyancer",
      "createdAt": "2024-09-22T12:15:33Z",
      "updatedAt": "2024-09-22T12:15:50Z"
    },
    ...
  ],
  "scroll_param": "MjAyNC0wOS0yNFQxNDozMTozN1o="
}

Export Endpoints

There is one type of export available, allowing you to fetch up to 200 dynamically-generated records with dummy data each time the server is run locally using the playground start command.

1. Export CSV

  • Endpoint: /export/csv
  • Method: GET
  • Response:
    • CSV file
  • Sample Request: 
    curl -X GET http://127.0.0.1:5001/export/csv/
  • Sample Response: 
    CSV File

Incremental Sync Endpoints

There are three types of incremental sync available, allowing you to fetch up to 200 dynamically-generated records with dummy data each time the server is run locally using the playground start command.

1. Timestamp Incremental Sync

  • Endpoint: /incremental/timestamp
  • Method: GET
  • Query Parameters:
    Parameter Type Required Description
    since string No Return items updated since this timestamp. Format: YYYY-MM-DDTHH:MM:SSZ.
  • Response:
    • data: Array of items updated since the specified timestamp.
  • Sample Request: 
    curl -X GET http://127.0.0.1:5001/incremental/timestamp?since=2024-09-22T12:00:00Z
  • Sample Response: 
    {
  "data": [
    {
      "id": "1989d8f6-57a5-41bf-b21b-4d6de6db6de6",
      "name": "XYZ",
      "email": "xyz@example.net",
      "address": "Some Random Address, AS 18073",
      "company": "Nguyen, Nash and King",
      "job": "Licensed conveyancer",
      "createdAt": "2024-09-22T12:15:33Z",
      "updatedAt": "2024-09-22T12:15:50Z"
    },
    ...
  ]
}

2. Step-size Incremental Sync

  • Endpoint: /incremental/step
  • Method: GET
  • Query Parameters:
    Parameter Type Required Description
    start_id integer Yes Starting ID for the range of items to retrieve.
    end_id integer Yes Ending ID for the range of items to retrieve.
  • Response:
    • data: Array of items within the specified ID range.
  • Sample Request: 
    curl -X GET http://127.0.0.1:5001/incremental/step?start_id=1&end_id=10
  • Sample Response: 
    {
  "data": [
    {
      "id": "1",
      "name": "XYZ",
      "email": "xyz@example.net",
      "address": "Some Random Address, AS 18073",
      "company": "Nguyen, Nash and King",
      "job": "Licensed conveyancer",
      "createdAt": "2024-09-22T12:15:33Z",
      "updatedAt": "2024-09-22T12:15:50Z"
    },
    ...
  ]
}

Auth Endpoints

There are following type of auth endpoints available, allowing you to fetch up to 20 dynamically-generated records with dummy data each time the server is run locally using the playground start command.

Note: The Auth credentials are dynamic and are displayed in the log message each time the server is run locally using the playground start command.

1. Http Basic Auth

  • Endpoint: /auth/http_basic
  • Method: GET
  • Request Headers:
    • Authorization: Basic <Base64Encoded(YOUR_USERNAME:YOUR_PASSWORD)>
  • Response:
    • data: Array of items retrieved.
  • Sample Request: 
    curl -X GET http://127.0.0.1:5001/auth/http_basic -H "Authorization: Basic DN45HBWEDN3ECSAET5VSDVSDVSDS32ECSDCASC="
  • Sample Response: 
        {
  "data": [
    {
      "id": "1989d8f6-57a5-41bf-b21b-4d6de6db6de6",
      "name": "XYZ",
      "email": "xyz@example.net",
      "address": "Some Random Address, AS 18073",
      "company": "Nguyen, Nash and King",
      "job": "Licensed conveyancer",
      "createdAt": "2024-09-22T12:15:33Z",
      "updatedAt": "2024-09-22T12:15:50Z"
    },
    ...
  ],
}

2. Http Bearer Auth

  • Endpoint: /auth/http_bearer
  • Method: GET
  • Request Headers:
    • Authorization: Bearer <YOUR_BEARER_TOKEN>
  • Response:
    • data: Array of items retrieved.
  • Sample Request: 
    curl -X GET http://127.0.0.1:5001/auth/http_bearer -H "Authorization: Bearer D4DV3RVSDVY5CSAETXBsZS5E3RFDSCSDCDSCFDE4="
  • Sample Response: 
        {
  "data": [
    {
      "id": "1989d8f6-57a5-41bf-b21b-4d6de6db6de6",
      "name": "XYZ",
      "email": "xyz@example.net",
      "address": "Some Random Address, AS 18073",
      "company": "Nguyen, Nash and King",
      "job": "Licensed conveyancer",
      "createdAt": "2024-09-22T12:15:33Z",
      "updatedAt": "2024-09-22T12:15:50Z"
    },
    ...
  ],
}

3. API Key Auth

  • Endpoint: /auth/api_key
  • Method: GET
  • Request Headers:
    • Authorization: apiKey <YOUR_API_KEY>
  • Response:
    • data: Array of items retrieved.
  • Sample Request: 
    curl -X GET http://127.0.0.1:5001/auth/api_key -H "Authorization: apiKey D4CVE3MDlA23DCCSAETXBsZS5jb2063VERSCI4Y23RVSD="
  • Sample Response: 
        {
  "data": [
    {
      "id": "1989d8f6-57a5-41bf-b21b-4d6de6db6de6",
      "name": "XYZ",
      "email": "xyz@example.net",
      "address": "Some Random Address, AS 18073",
      "company": "Nguyen, Nash and King",
      "job": "Licensed conveyancer",
      "createdAt": "2024-09-22T12:15:33Z",
      "updatedAt": "2024-09-22T12:15:50Z"
    },
    ...
  ],
}

4. Session Token Auth

Login Endpoint

  • Endpoint: /auth/session_token/login
  • Method: POST
  • Request Body Parameters:
    Parameter Type Required Description
    username string Yes Your username.
    password string Yes Your password
  • Response:
    • token: String token value
  • Sample Request: 
    curl -X POST http://127.0.0.1:5001/auth/session_token/login -H "Content-Type: application/json" \
 -d '{"username": "test_user", "password": "test_password"}'
  • Sample Response: 
    {
  "token": "ZDE3MDlAZXhhbXBsZS5jb206YzYzZjI4Y2JiNQ=="
}

Data Endpoint

  • Endpoint: /auth/session_token/data
  • Method: GET
  • Request Headers:
    • Authorization: Token <YOUR_SESSION_TOKEN>
  • Response:
    • data: Array of items retrieved.
  • Sample Request: 
    curl -X GET http://127.0.0.1:5001/auth/session_token/data -H "Authorization: Token ZDE3MDlAZXhhbXBsZS5jb206YzYzZjI4Y2JiNQ=="
  • Sample Response: 
        {
  "data": [
    {
      "id": "1989d8f6-57a5-41bf-b21b-4d6de6db6de6",
      "name": "XYZ",
      "email": "xyz@example.net",
      "address": "Some Random Address, AS 18073",
      "company": "Nguyen, Nash and King",
      "job": "Licensed conveyancer",
      "createdAt": "2024-09-22T12:15:33Z",
      "updatedAt": "2024-09-22T12:15:50Z"
    },
    ...
  ],
}

5. Cursor Endpoints

Companies Cursor

  • Endpoint: /cursors/companies

  • Method: GET

  • Query Parameters:

    Parameter Type Required Description
    order_by string No Parameter to order by. Allowed values: createdAt, updatedAt. Default: updatedAt.
    order_type string No Sorting order. Allowed values: asc, desc. Default: asc.
    updated_since string No Return items updated since this timestamp. Format: YYYY-MM-DDTHH:MM:SSZ.

  • Response:

    • data: Array of companies.
    • total_items: Total number of companies after filtering.

  • Sample Request:

    curl -X GET http://127.0.0.1:5001/cursors/companies

  • Sample Response:

    {
  "data": [
    {
      "company_id": 1,
      "company_name": "Johnson-Miller",
      "createdAt": "2024-09-22T12:15:33Z",
      "updatedAt": "2024-09-22T12:15:50Z"
    },
    ...
  ],
  "total_items": 6
}

Departments by Company

  • Endpoint: /cursors/<company_id>/departments

  • Method: GET

  • Path Parameters:

    Parameter Type Required Description
    company_id integer Yes The ID of the company to get departments for.

  • Query Parameters:

    Parameter Type Required Description
    order_by string No Parameter to order by. Allowed values: createdAt, updatedAt. Default: updatedAt.
    order_type string No Sorting order. Allowed values: asc, desc. Default: asc.
    updated_since string No Return items updated since this timestamp. Format: YYYY-MM-DDTHH:MM:SSZ.

  • Response:

    • data: Array of departments for the specified company.
    • total_items: Total number of departments after filtering.

  • Sample Request:

    curl -X GET http://127.0.0.1:5001/cursors/1/departments

  • Sample Response:

    {
  "data": [
    {
      "department_id": 1,
      "company_id": 1,
      "department_name": "Engineering",
      "createdAt": "2024-09-22T12:15:33Z",
      "updatedAt": "2024-09-22T12:15:50Z"
    },
    ...
  ],
  "total_items": 4
}

Error Responses

  • 400 Bad Request: Returned for validation errors or unexpected query parameters.

    • Example: {"error": "Invalid value for 'order_by'. Use 'createdAt' or 'updatedAt'."}
    • Example: {"error": "Both 'start_id' and 'end_id' parameters are required"}
    • Example: {"error": "Invalid value for 'start_id'. It must be greater than or equal to 1."}
    • Example: {"error": "Invalid value for 'end_id'. It must be greater than or equal to 'start_id'."}

  • 404 Not Found: Returned when the requested resource does not exist.

    • Example: {"error": "company_id '1' not found"}

Maintenance

This package is actively maintained by Fivetran Developers. Please reach out to our Support team for any inquiries.

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for fivetrandevelopers from gravatar.com fivetrandevelopers Avatar for fivetran-satvik from gravatar.com fivetran-satvik Avatar for rishabh.ghosh from gravatar.com rishabh.ghosh Avatar for varun-fivetran from gravatar.com varun-fivetran
Meta

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License
  • Requires: Python >=3.10
Classifiers

Release history Release notifications | RSS feed

1.1.3

1.1.2

This version

1.1.1

1.1.0

1.0.0

0.12.12.1

0.11.21.1

0.11.14.1

0.10.15.1

0.10.3.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

fivetran_api_playground-1.1.1.tar.gz (16.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

fivetran_api_playground-1.1.1-py3-none-any.whl (12.6 kB view details)

Uploaded Python 3

File details

Details for the file fivetran_api_playground-1.1.1.tar.gz.

File metadata

  • Download URL: fivetran_api_playground-1.1.1.tar.gz
  • Upload date:
  • Size: 16.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.10.8

File hashes

Hashes for fivetran_api_playground-1.1.1.tar.gz
Algorithm Hash digest
SHA256 f611449c12cd4c933af697e90c75e73521e7aa21a302e9524dd421d4f82890a8
MD5 2543ff3409351a7c16e7f0d69a85d23c
BLAKE2b-256 62c2feda9423d934ddd26853b5ba00ca51c792e6aed86486a65a31702f7dc461

See more details on using hashes here.

File details

Details for the file fivetran_api_playground-1.1.1-py3-none-any.whl.

File metadata

File hashes

Hashes for fivetran_api_playground-1.1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 11783026368717c363523aca218a0a765664899cf6b29aea7648ec0efa02a2fa
MD5 6ba0da303d1f13b147a09e7c9cf41f44
BLAKE2b-256 626845128119bade97df2e98c2104cf41abe2a9f7612655623c0e8d972e0736c

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page