Skip to main content

Route Families

Ikawaari currently exposes multiple implemented API families, with an ongoing harmonization effort toward a more uniform structure.

This page explains how to read the platform API surface correctly, and which route form should now be treated as canonical.

Why route families matter​

Different capabilities are exposed through different route groups, depending on whether the caller is:

  • a server-to-server integration using API keys
  • a merchant-authenticated dashboard or merchant client
  • a checkout session or hosted checkout flow
  • a module-specific integration such as escrow, billing, or marketplace

Core route families​

Public or API-key oriented resources​

The canonical shape for versioned public APIs is now:

  • api/v1/<resource>

Public resources should use plural, RESTful, kebab-case names. Examples include:

  • api/v1/payment-intents
  • api/v1/webhook-endpoints
  • api/v1/payouts
  • api/v1/balance
  • api/v1/balance-transactions

For the already harmonized public perimeter, duplicate legacy routes have been removed to avoid confusion. New integrations, SDKs, and documentation examples must use these canonical routes only.

Dashboard and merchant account route families​

Some capabilities used by the merchant dashboard exist under dedicated authenticated families. They are documented in dashboard guides when relevant to merchant usage, but they should not be treated as public server integration endpoints.

Checkout route families​

Checkout-related functionality is currently split between a versioned public API and a hosted checkout surface that is not yet fully normalized:

  • api/v1/checkout/sessions
  • api/checkout/*

The target direction is:

  • public resource creation and management via api/v1/...
  • hosted checkout runtime endpoints progressively migrated toward a coherent documented structure

Product and module route families​

Implemented domains also have dedicated route groups, including:

  • api/v1/escrow/*
  • api/v1/billing/*
  • api/v1/marketplace/*
  • api/v1/payout-engine/*
  • api/v1/funding/*

System endpoints​

System endpoints are not public integration endpoints. They include:

  • health and availability
  • metrics
  • provider callbacks
  • system webhooks

For this category, URL stability matters more than application API versioning.

Canonical design rule​

Going forward, the target rule is:

  • Public APIs: api/v{version}/resource
  • Dashboard/merchant account APIs: authenticated routes documented only when they map to public merchant usage
  • System APIs: unversioned

New resources should avoid:

  • root-level routes without a namespace
  • singular names for collections
  • snake_case URL segments
  • mixing v1/resource, /resource, and api/resource for the same capability

Documentation rule​

Ikawaari documentation should primarily document the recommended canonical route shape. Compatibility aliases should only be mentioned when they are truly still active for the relevant surface.

The goal is to stay exact first, then progressively improve consistency, governance, and generated reference coverage over time.