Postel’s Law and APIs: Why Being Flexible Matters

Have you ever built an API and wondered, "Should I be strict with what I accept, or more forgiving?" That's exactly where Postel’s Law (also called the Robustness Principle) comes in.

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

Jon Postel, one of the pioneers of the internet, came up with this rule while working on TCP/IP, and honestly, it’s just as relevant today, especially when designing APIs.

Let’s break it down and see why it matters.

Be liberal in what you accept

Think of your API as a great host, one that doesn’t freak out just because a guest shows up wearing mismatched socks. Your API should gracefully handle minor variations in requests instead of rejecting them outright.

Extra fields? No problem

• A client sends GET /users/123?unusedParam=true.
• Instead of throwing an error, your API just ignores unusedParam and processes the request normally.

Different date formats? Accept them

• One client sends GET /users?registered_after=2024-01-01, another sends GET /users?registered_after=01-01-2024.
• Instead of rejecting one, your API should normalize the format internally.

Case sensitivity? Don’t be picky

• Someone sends { "name": "ALICE" }, another sends { "name": "alice" }.
• Your API shouldn’t care. It should handle both consistently.

By being flexible, you avoid unnecessary client-side errors and make integration way smoother.

Be conservative in what you send

While your API should be forgiving with what it receives, it should be very careful about what it sends back. Think of it like this: you wouldn’t give someone a different home address every time they ask, right?

Keep the JSON structure consistent

If your API response is:

{
  "id": 123,
  "name": "Alice",
  "email": "[email protected]",
  "created_at": "2024-03-22T12:00:00Z"
}

It should stay that way, even if you later add new fields.

Don’t rename or remove fields randomly

If a client is expecting "name" and "email", suddenly changing them to "fullName" and "contact" will break their app.

Versioning is your friend

If you really need to make breaking changes, use API versioning (/v1/users vs /v2/users) instead of messing with existing responses.

When your API’s response structure is predictable, developers trust it more and avoid unnecessary debugging nightmares.

A real-world example

Let’s say I’m building a user profile API where clients fetch user details like this:

GET /users/123

What my API accepts

• Extra parameters work fine (?sort=asc or ?foo=bar).
• Different date formats are accepted for filtering (YYYY-MM-DD, MM-DD-YYYY).

What my API sends back

{
  "id": 123,
  "name": "Alice",
  "email": "[email protected]",
  "created_at": "2024-03-22T12:00:00Z"
}

• A consistent structure, with no unexpected renames or removals.
• If new fields are added, existing ones stay the same.

Why Postel’s Law makes your API better

• More developer-friendly: clients don’t need to worry about every tiny variation in a request.
• Fewer breaking changes: your API stays backward-compatible, which saves everyone headaches.
• Better interoperability: different teams and services can work with your API without struggling against rigid rules.

Summary

Postel’s Law might sound simple, but trust me, it’s a game changer when building reliable, flexible APIs. The rule of thumb:

• Be forgiving with inputs.
• Be predictable with outputs.

Stick to that, and your API will be much easier to use and maintain. Happy coding!