Write your own Ocean integration

After scaffolding, implement the third-party logic, configuration, and deployment for your custom-coded Ocean integration.

Your code should return raw objects from the third-party API. Keep those objects mapping-agnostic so users can change how data appears in Port without changing your Python code. Port applies the mapping configuration and updates the catalog.

Build flow

1. Define configuration files - .port/spec.yaml, optional blueprints and default mapping.
2. Implement an API client - authenticate and paginate with Ocean's async HTTP client.
3. Handle resyncs - @ocean.on_resync handlers that yield batches of raw data.
4. Implement incremental sync - optional @ocean.on_incremental_resync handlers for changed-since fetches.
5. Kinds and selectors - optional custom mapping fields in integration.py.
6. Implement live events - optional webhook processors.
7. Test and run locally - env vars, make run, and resync triggers.
8. Development guidelines - httpx, logging, performance, and raw-data practices.
9. Deploy - Docker and Helm with your private image.

Reference

• Ocean and event contexts - ocean and event globals.
• Configuration validation - types in spec.yaml.
• Ocean framework - event listeners, live events runtime, actions, probe, and advanced configuration.