Custom-coded Ocean integration
If the no-code Ocean custom integration does not meet your needs, you can build a custom-coded Ocean integration in Python using Port's open-source Ocean framework.
Your integration's job is to extract raw data from a third-party system (and optionally handle live events and actions). You also author the mapping configuration that describes how that raw data becomes Port entities. Port applies the mapping and updates the catalog.
For how Ocean runs once installed (event listeners, live events, actions, and more), see the Ocean framework section.
No-code vs custom-coded
| No-code Ocean custom integration | Custom-coded Ocean integration | |
|---|---|---|
| How you build it | Configuration only (endpoints, auth, JQ mapping). | Python code with the Ocean framework. |
| Best for | REST APIs that return JSON over HTTP. | Complex auth, pagination, nested data, or non-standard APIs. |
| Live events | Currently not supported. | Full control via Ocean event processors. |
| Maintenance | Port hosts the runtime (or you run the generic custom image). | You own the app, image, and deployment. |
Start with the no-code option when it covers your API. Choose custom-coded when you need logic that configuration alone cannot express.
When to build a custom-coded Ocean integration
Choose a custom-coded Ocean integration when:
- You need custom authentication flows (OAuth2, JWT refresh, and similar).
- The API has complex pagination, nested data, or kind-specific selectors.
- You need live events that the no-code Ocean custom integration cannot express.
- You want a dedicated Python app for one system, maintained outside the Ocean monorepo.
If you only need to call a REST API with config and JQ mapping, start with the no-code Ocean custom integration instead.
What you implement
| Responsibility | Where |
|---|---|
Fetch raw data per kind | @ocean.on_resync() in main.py. |
| Optional incremental sync | @ocean.on_incremental_resync() handlers that use the active cursor. |
| Optional live events | Live event processors that return updated or deleted raw objects. |
| Optional actions | Action executors registered with Ocean. |
| Integration config schema | .port/spec.yaml. |
| Default blueprints and mapping | .port/resources/. |
| Custom mapping selectors | Optional integration.py classes. |
Ocean core handles connecting to Port, listening for resync requests, receiving webhooks, and reporting sync status. See how an Ocean integration runs.
Build path
- Getting started - install the CLI, scaffold, and run locally.
- Write your own Ocean integration - config, API client, resyncs, incremental sync, live events, testing, and deploy.
Contribute publicly
To share an integration with the Port community, develop it in the Ocean monorepo and follow the repository contributing guide. Scaffolding with ocean new is the default for org-specific integrations.