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.14
  • 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

This version

1.1.3

1.1.2

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.3.tar.gz (16.1 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.3-py3-none-any.whl (12.6 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: fivetran_api_playground-1.1.3.tar.gz
  • Upload date:
  • Size: 16.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.13.7

File hashes

Hashes for fivetran_api_playground-1.1.3.tar.gz
Algorithm Hash digest
SHA256 ce4ae31a7f18d3ec46d51b1135d319fff4e2838631863f0fa15ada5a5ffc5815
MD5 df9087f4e2a87bf47152dc297d09053e
BLAKE2b-256 32f1757826f1812842b55d020c90c51602f129ac8535025bd0a41df19bed0707

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for fivetran_api_playground-1.1.3-py3-none-any.whl
Algorithm Hash digest
SHA256 c10224b12acbdb72c5935efdc7c1a954eaca641ead6e31ae6d326f04aa76b6ad
MD5 f10d98d4e41ef1da6c4206e271aa19d9
BLAKE2b-256 485711ac62bf590d775686ed49971524bc35bbd3c511452e7f8f7cd3bf583a39

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