Principle:Langgenius Dify APIContracts
| Knowledge Sources | Dify |
|---|---|
| Domains | Frontend, API, TypeScript |
| Last Updated | 2026-02-12 07:00 GMT |
Overview
API Contracts defines the type-safe API contract patterns using oRPC that enable compile-time validation of API interactions in the Dify frontend.
Description
The API Contracts principle establishes how the Dify frontend defines, validates, and consumes API endpoints through a type-safe contract layer. Using oRPC (a typed RPC framework), the frontend declares the shape of each API request and response as TypeScript types, creating a contract that is enforced at compile time. This eliminates the runtime surprises that occur when the backend API changes shape without the frontend being updated accordingly.
The contract router organizes API definitions into logical groups that mirror the backend's domain structure. Each route definition specifies the HTTP method, path parameters, query parameters, request body shape, and response type. These definitions serve as both documentation and executable specifications, providing developers with autocompletion and type checking when making API calls while also enabling automated generation of API client code.
The principle promotes a contract-first development workflow where API changes begin with updates to the contract definitions. Frontend and backend developers can then work independently against the agreed-upon contract, with the type system ensuring that both sides remain compatible. When breaking changes are necessary, the compile-time errors produced by updating the contract guide developers to all call sites that need modification, making API evolution safe and systematic.
Usage
Use this principle when:
- Adding new API endpoints or modifying existing endpoint contracts
- Implementing the frontend API client layer that consumes backend services
- Validating API compatibility between frontend and backend during development
Theoretical Basis
API Contracts draws from Design by Contract principles (Bertrand Meyer), where software components define formal agreements about their interfaces. The typed RPC approach extends this concept with the type system serving as the contract enforcement mechanism. The pattern also aligns with Consumer-Driven Contract Testing, where the consumer's expectations drive the contract definition, and the Schema-First API Design methodology from the API design community.