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; }

You run a compiler against the IDL file. For Protobuf that is protoc plus a language plugin; for Thrift it is the thrift binary; for OpenAPI it is a tool like openapi-generator. The compiler reads the schema and emits source files.

On the client side you get typed stub functions: calling getUser(id) serializes your request into the wire format, sends it, and deserializes the response back into a typed object. On the server side you get an interface or abstract base class with the same method signatures, and you fill in the business logic. Neither side hand-writes serialization or parsing.

The field numbers you see in Protobuf (id = 1, name = 2) are what travels on the wire, not the field names. That is why you can rename a field freely, and why you must never reuse or change an existing field number. Adding a new field with a new number is backward compatible: old clients ignore numbers they do not recognize, and new fields default to zero or empty.

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.

Imagine a checkout service written in Go that needs to call a fraud-scoring service written in Python. Without an IDL, the Go team writes JSON-marshalling code by hand, the Python team writes parsing code by hand, and a renamed field or a string-versus-int mismatch is found only at runtime in production.

With a Protobuf IDL, both teams compile the same fraud.proto. The Go side gets a typed client, the Python side gets a typed servicer base class. If someone changes the schema in an incompatible way, the build fails before anything ships. The two services have never seen each other's source code, yet they agree precisely on every byte they exchange.