Skip to main content

Schema Design: API-first, Protobuf, and MCP

Schema design is the foundation of any API-first system. In HAPI, your Protocol Buffers (protobuf) schema defines not just RPC methods, but also the structure, validation, and semantics of every request and response.

Principles of Good Protobuf Schema Design​

  • Explicitness: Define all fields, types, and constraints clearly.
  • Validation: Use field options, types, and custom validation logic.
  • Reusability: Use message definitions and imports to avoid duplication.
  • Extensibility: Leverage protobuf extensions for MCP-specific needs.
tip

Design your protobuf schemas with future agents and tools in mind. Well-structured schemas make it easier for MCP-powered agents to reason about and use your API.

Example: User Message​

message User {
  string id = 1;
  string name = 2;
  string email = 3;
  repeated string roles = 4;
}

Using Enums and Constraints​

enum Status {
  ACTIVE = 0;
  INACTIVE = 1;
  PENDING = 2;
}
caution

Avoid using generic types like google.protobuf.Any unless necessary. This can make validation and documentation less effective.

Best Practices​

  • Use message definitions to share common models across RPCs.
  • Document all fields, even optional ones, using comments.
  • Use field options for validation and constraints.
  • Validate with tools like protoc and gRPC code generators.

Further Reading​