Date:

Share:

Postel’s law for API Robustness | Code4IT

Related Articles

Table of Contents

When designing and building APIs for the web, we must follow Postel’s Law to make our APIs stronger.

Given the original definition, the law states that you must

Be conservative in what you do, be liberal in what you receive from others

But it is often reformulated as

Be conservative in what you send, be liberal in what you receive

ok what? But what does that actually mean?

Robustness: a characteristic of software quality

Before we talk about Postel’s Law, we should spend just a few words about resilience.

It is quite difficult to find a definition of resilience. But we can say that Resilience is a property of a system not to break in case of minor changes.

It noted Stability and reliability are not the same thing: a reliable system if it can work properly for a certain period of time under certain conditions: for example, a reliable system should be able to work in case of unexpected errors, should be available to users and so on. Durability is a slightly different quality attribute.

Now, there’s a problem with robustness as a quality attribute: it’s hard to measure. so? Should we really care about this? Yes.

Postal law applies to APIs

Let’s go back to Postel’s law.

It was first introduced in RFC definition of TCPin 1980.

This section (which is quite short, indeed) states that:

TCP implementations should follow a general principle of robustness: be conservative in what you do, be liberal in what you receive from others.

This was a golden rule used to define the TCP protocol, but it has been adapted to API definitions (well, with some common sense):

Be conservative in what you send, be liberal in what you receive

What does that mean, in the end?

Let me explain this with an example: you are building an API used to integrate a bookstore.

It exposes only one method:

with a few query string parameters: name and year. This endpoint returns a list of books.

Now, how can we make this endpoint robust?

Be conservative in what you send

When a client calls you, don’t change the returned result to avoid breaking changes.

So, for example, if your endpoint returns

{
    "id": 123,
    "title": "My wonderful book",
}

Note that all callers expect to receive these two fields with these exact names.

Postel’s rule says that you must not change the names of existing assets: this will make your system robust and prevent regressions.

Obviously, the more fields you expose, the higher the probability of adding regressions; Return only the fields you really need!

Some basic rules to “be conservative”:

  1. Do not rename existing properties;
  2. Do not change the type of existing properties: if you have set year As a number, don’t change it to a string;
  3. APIs should return only necessary properties: the more fields you add, the higher the probability of creating regressions.

Be liberal in what you get

On the other hand, we should not be too strict about what our system should accept.

Here is a valid API call to our system:

GET /books?name=eragon&year=2002

how can we Be liberal in what we receive?

For example, we Do not need Return a bad request in case the caller adds some unrecognized parameters:

GET /books?name=eragon&year=2002&not_existing_property=value

no_property_exists is not one of the parameters supported by our API: we should just ignore it.

Some basic rules to “be liberal”:

  1. ignore unsupported parameters (not only valid for query string but also for HTTP headers and HTTP body);
  2. Don’t let it all go: Always validate input;
  3. receive different types of data; Say your system treats years as numbers: if the caller sends you a year as a string, try to convert it as an integer;

How to embrace change?

OK, but our systems have to evolve – they can’t be frozen forever. How can we make our systems evolve but still be robust?

First of all, we must follow the basic rules listed above. But then we need some ways to develop new functionality without affecting customers.

A good first approach is through feature flags: We can develop new functions and enable them only when they are thoroughly tested (We must also check against regressions). So we can only release this new functionality to a subset of the total users to see if we really missed something.

Sure, good Version management It is essential: customers need to be able to understand what functions and changes are available in a specific version.

And finally, instead of removing things, like API endpoints or parameters, we should cancel them and tell consumers that we will remove them in the future version of the API.

Ultimately, the golden rule is: communicate clearly. Good internal documentation, clear communication with customers, etc.

In this way, we make our APIs robust and reliable.

Additional readings

The RFC 761 that described TCP and contains the first definition of Postel Law is public:

🔗 The principle of resilience RFC 761

On IBM’s website you can find more details about resilience and Postal Law. If you are interested in this topic, I highly recommend reading this article:

🔗 Firmness IBM Cloud

This article first appeared on Code4IT 🐧

Finally, here’s some more interesting content about robustness and Postel’s law, with some examples in Java:

🔗 Why you should follow the principle of resilience in your APIs | Jose Coscia

As we said, it’s important to clearly communicate what endpoints, parameters, and return objects are available in our APIs. A good way to do this in .NET applications is using Swagger. In particular, you may want to add different documentation based on different versions. Here’s a quick tip on how to specify versions in Swagger

🔗 Understanding Swagger Integration in .NET Core | Code4IT

finishing

In this article, we learned that Postel’s rule helps us set a path to creating robust APIs.

In short, we must validate our inputs, be explicit about what we receive and what we return, and do our best not to create regressions.

I hope you enjoyed this article! Let’s keep in touch Twitter or on LinkedIn, If you want! 🤜🤛

Happy coding!

🐧

.

Source

Popular Articles