> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Implement an API client

The API client is the only place that should talk to the third-party system. Keep authentication, pagination, and rate limiting there, and call the client from resync handlers and live event processors.

Use Ocean's async HTTP client​

Prefer http_async_client from Ocean instead of requests or a new httpx.AsyncClient. Ocean's client is shared, async-friendly, and aligned with Ocean's retries, timeouts, and logging.

from httpx import Timeout
from port_ocean.context.ocean import ocean
from port_ocean.utils import http_async_client


class MyClient:
    def __init__(self) -> None:
        self.base_url = ocean.integration_config["apiBaseUrl"].rstrip("/")
        self.client = http_async_client
        self.client.headers["Authorization"] = (
            f"Bearer {ocean.integration_config['apiToken']}"
        )
        self.client.timeout = Timeout(30)

Read secrets and settings from ocean.integration_config. Keys match the camelCase name values in .port/spec.yaml.

Pagination and batching​

Fetch pages from the third-party API and yield batches of raw objects (lists of dicts). Do not load the entire dataset into memory when the API supports pagination.

from typing import Any, AsyncGenerator


async def get_paginated_items(self) -> AsyncGenerator[list[dict[str, Any]], None]:
    url = f"{self.base_url}/items"
    params: dict[str, Any] = {"limit": 100}
    while url:
        response = await self.client.get(url, params=params)
        response.raise_for_status()
        body = response.json()
        yield body["items"]
        url = body.get("next")
        params = {}

Practices​

  • Keep I/O async so you do not block Ocean's event loop.
  • Centralize request helpers so auth headers and error handling stay consistent.
  • If you register webhooks in the third-party system on startup, put that logic on the client and call it from @ocean.on_start().
  • Return API payloads as close to the source as practical. Enrich with custom fields only under keys that start with __ (for example __team_id) so they do not collide with upstream fields.

Next steps​