IDL

An IDL is a small, declarative file that says nothing about how your code runs and everything about how two programs talk to each other. It lists the service methods, the messages those methods send and receive, and the type of every field. Protocol Buffers (.proto), Apache Thrift (.thrift), and OpenAPI (formerly Swagger, written in YAML or JSON) are the IDLs you will see most often.

The point is that the contract lives in one place and is the single source of truth. A team in Go and a team in Python do not exchange handwritten parsing code or English docs that drift out of date. They both compile the same IDL file and get types and stubs that are guaranteed to line up.

Here is a tiny Protobuf example. It defines a service with one method and the two messages it uses:

service UserService { rpc GetUser (GetUserRequest) returns (User); } message GetUserRequest { int64 id = 1; } message User { int64 id = 1; string name = 2; string email = 3; }

Reach for an IDL when you have services in more than one language, or when many teams call the same API and you need a contract that cannot silently drift. Binary IDLs like Protobuf and Thrift also give you compact payloads and fast parsing, which matters for high-traffic internal RPC. gRPC is built directly on Protobuf for exactly this reason.

The cost is a build step and some ceremony. You add a code-generation stage to your pipeline, and the generated binary formats are not human readable, so you debug with tooling like grpcurl instead of curl plus your eyes. For a small public REST API consumed by browsers, plain JSON with no codegen is often simpler.

OpenAPI sits in the middle. It describes JSON-over-HTTP APIs, so the payloads stay human readable, and it can still generate clients, server stubs, and interactive docs. You trade the compactness of binary formats for the universal reach of HTTP and JSON. Pick the binary IDLs for internal performance-sensitive RPC, and OpenAPI when the API is REST and the consumers are diverse.