Open API Business Logic
Business service layer backing the Open API endpoints
Background
Isolated business logic layer that transforms internal service data into external-consumer-friendly formats for the Open API gateway. Maintains a strict boundary between internal domain models and externally exposed contracts.
Architecture
openapi gateway → gRPC call → openapibiz (go-zero) → input validation/sanitization → internal gRPC services → response transformation → error code mapping → openapi gateway → external client.
Key Implementations
Data Transformation Layer
Converts internal domain models into versioned external DTOs, mapping field names, units, and structures to the published API contract.
Why: Decoupling internal and external schemas allows internal services to evolve independently without breaking third-party integrations.
Input Validation and Sanitization
All external inputs are validated against strict schemas and sanitized before forwarding to internal services.
Why: External input is untrusted; validation at this layer prevents malformed or malicious data from reaching internal service logic.
Error Code Mapping
Internal error codes and gRPC status codes are translated into documented external error codes with consumer-friendly messages.
Why: Exposing internal error details leaks implementation information; mapped codes give integrators actionable feedback without revealing internals.
Technical Decisions
| Technical Decisions | Chosen | Alternative | Reason |
|---|---|---|---|
| Business logic isolation | Separate openapibiz service | Inline logic in openapi gateway | A dedicated service keeps the gateway focused on auth and routing while business logic changes deploy independently. |
| Internal communication | gRPC | REST over HTTP | gRPC provides type-safe contracts, efficient binary serialization, and streaming support for internal service-to-service communication. |