Postel's Law: The Secret to Building APIs That Don't Break

Imagine you've built an API for user registration. Your documentation says the request should look like this:

{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 25
}

Everything works perfectly. A month later, another team starts integrating with your API. Their request looks like this:

{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 25,
  "debug": false,
  "device": "iPhone"
}

Your API immediately rejects it. Why? Because it received two fields it wasn't expecting.

The client is frustrated. The integration is delayed. Nothing was actually wrong with the request — your API was simply too strict.

This is exactly the kind of problem Postel's Law helps solve.

What Is Postel's Law?

Postel's Law states:

"Be conservative in what you send, and liberal in what you accept."

At first glance, this sounds contradictory. Let's break it down.

Be Conservative in What You Send

When your API sends data to another application, it should be predictable. Only send fields that are documented. Avoid unnecessary information. Keep responses clean and consistent.

A good response:

{
  "id": 101,
  "name": "John Doe",
  "email": "john@example.com"
}

A bad response:

{
  "id": 101,
  "name": "John Doe",
  "email": "john@example.com",
  "debug": true,
  "internalCacheId": "XJ19P",
  "serverVersion": "4.8.2-beta"
}

Those extra fields may expose implementation details or confuse API consumers. When you send data, be precise.

Be Liberal in What You Accept

This is where most developers make mistakes. Suppose your API only needs:

{
  "name": "John Doe",
  "email": "john@example.com"
}

A client sends:

{
  "name": "John Doe",
  "email": "john@example.com",
  "theme": "dark",
  "language": "English"
}

Should your API fail? Probably not. Those extra fields don't affect registration. You can simply ignore them. Your API still works, the client is happy, and everyone wins.

A Real-World Analogy

Imagine ordering coffee. You say: "I'd like a cappuccino." The barista asks: "Small, medium, or large?" You reply: "Medium, please. Also, it's my birthday today."

The barista doesn't respond: "Sorry, I wasn't expecting that last sentence." They simply ignore the irrelevant information and continue making your coffee.

Good APIs behave the same way.

Why Does This Matter?

APIs rarely live in isolation. They are consumed by:

• Mobile applications
• Web applications
• Third-party developers
• Internal services
• Future versions of your own software

You don't control every client. Different teams may use different programming languages, frameworks, or serialization libraries. Some libraries automatically include extra fields. Others send values in a different order. Some include optional metadata.

A rigid API becomes difficult to integrate with. A flexible API survives these differences gracefully.

A Good Example

Suppose your API expects:

{
  "username": "alice",
  "password": "secret123"
}

A mobile app later adds analytics information:

{
  "username": "alice",
  "password": "secret123",
  "device": "Android",
  "appVersion": "3.1.0"
}

Your authentication logic only needs the username and password. Ignore the rest. The login succeeds. No changes are required.

A Bad Example

Some APIs validate every single field. The moment they encounter an unexpected property:

{
  "error": "Unexpected field: appVersion"
}

Now every client must remove that field before sending requests. One unnecessary validation creates extra work for every consumer.

Does This Mean Accept Everything?

No. This is one of the biggest misconceptions about Postel's Law. Being liberal doesn't mean accepting invalid data. For example:

{
  "email": "not-an-email"
}

or

{
  "age": -50
}

or

{
  "password": ""
}

These should absolutely be rejected. Postel's Law is about tolerating harmless differences, not ignoring invalid input. Always validate the data your application actually depends on.

What About Responses?

The first half of Postel's Law is equally important. Imagine your API originally returns:

{
  "id": 25,
  "name": "Alice"
}

Months later, you decide to rename the field:

{
  "id": 25,
  "fullName": "Alice"
}

You just broke every client expecting "name". Instead, introduce the new field gradually while maintaining backward compatibility:

{
  "id": 25,
  "name": "Alice",
  "fullName": "Alice"
}

Eventually, after clients migrate, the old field can be deprecated. Stable responses build trust.

How Modern APIs Apply Postel's Law

Many successful APIs follow this principle. They typically:

• Ignore unknown request fields.
• Validate required fields carefully.
• Keep response formats stable.
• Introduce new fields without removing old ones immediately.
• Preserve backward compatibility whenever possible.

This allows APIs to evolve without constantly breaking integrations.

When Should You Be Strict?

There are situations where strict validation is the right choice — for example:

• Payment processing
• Banking systems
• Medical applications
• Authentication and authorization
• Security-sensitive operations

If an unexpected field could change behavior or introduce risk, rejecting the request is often safer. The goal isn't to be permissive everywhere — it's to be tolerant where it doesn't compromise correctness or security.

Key Takeaways

Whenever you build an API, remember these simple guidelines:

• Send only the data you've promised to send.
• Ignore extra fields that don't affect processing.
• Validate the fields your application depends on.
• Reject malformed or dangerous input.
• Design for backward compatibility so clients don't break when your API evolves.

Following these principles makes your APIs easier to integrate with, more resilient to change, and far less likely to cause frustrating breaking changes for other developers.

That's the essence of Postel's Law: be predictable when communicating, and be forgiving when listening.