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

Check out Port for yourself ➜ 

Development guidelines

Stay mapping-agnostic​

Yield raw third-party objects. Let users shape catalog entities through mapping. If you add computed fields, prefix them with __ (for example __owners) so they do not collide with upstream API fields.

Use async HTTP​

Use http_async_client from Ocean. Avoid synchronous requests calls on the event loop. See implement an API client.

Stream with generators​

In @ocean.on_resync handlers, yield batches instead of returning one giant list. That keeps memory stable and lets Ocean process data as it arrives.

@ocean.on_resync("project")
async def on_resync_projects(kind: str) -> ASYNC_GENERATOR_RESYNC_TYPE:
    client = MyClient()
    async for batch in client.get_paginated_projects():
        yield batch

Logging​

Use loguru:

from loguru import logger

logger.info("Fetched batch of {} projects", len(projects))

Live events​

Do not treat the webhook payload as the same shape as a resync response unless the third-party API guarantees that. Fetch the current resource in handle_event and return that raw object (or a delete). See implement live events.

Configuration access​

Read user settings from ocean.integration_config (camelCase keys from spec.yaml). During a resync, use event.resource_config for per-kind selectors.

Lint and types​

Run make lint (or your scaffold's equivalent) before you deploy. Keep type hints on public handlers and client methods.