Standalone Ocean integration
If the pre-built Ocean custom integration doesn't meet your needs, you can build a standalone Ocean integration from scratch using the Ocean framework.
When to build a standalone integration
- You need custom authentication flows (OAuth2, JWT refresh, etc.).
- The API has complex pagination or nested data structures.
- You want to contribute a reusable integration to the Ocean ecosystem.
Getting started
The Ocean framework documentation is the primary resource for building standalone integrations. It covers:
- Getting started with the Ocean CLI and project scaffolding.
- Developing an integration including lifecycle hooks, resource configurations, and webhook processors.
- Deploying an integration to Docker, Kubernetes, AWS ECS, or Azure Container Apps.
Project structure
A minimal Ocean integration requires:
my-integration/
├── main.py # Resync handlers and webhook processors
├── pyproject.toml # Python dependencies
├── Dockerfile # Container build instructions
└── .port/
└── spec.yaml # Integration specification
For a complete working example, see the integrations directory in the Ocean repository.
Key concepts
| Concept | Description |
|---|---|
@ocean.on_resync() | Handler that fetches data from your API during sync cycles. |
@ocean.on_start() | Hook that runs once when the integration starts. |
.port/spec.yaml | Defines configuration parameters users provide when installing. |
ocean sail | CLI command to run the integration locally. |