API is a promise not a contract

Alan Kay, often recognized as the “father of personal computers,” emphasized that the TCP/IP stack has undergone a complete code replacement over the years. Nevertheless, TCP/IP has maintained its full functionality and has consistently received updates, such as transitioning from IP V4 to IP V6. You can compare his talk on this topic through the following external link (Link 1).

According to Kay’s speech, the key to success lies in negotiation rather than contracts. Contracts tend to adopt an objective attitude of “you have to deal with it,” whereas negotiation fosters stability and adaptability.

An excellent example of stability over three decades is HTTP, which owes its success to the negotiation pattern. This pattern incorporates elements like the IETF RFC721 upgrade header field (Link 2) and the accept as well as content-type header. You can find more information on this subject through the following external links: (Link 3) and (Link 4).

The negotiation pattern is crucial for managing the notion that “APIs are forever,” as Amazon has stated (Link 5). This architectural pattern places the obligations on the API provider instead of the API consumer, promoting autonomy between modules. Hyrum’s laws (Link 6), as described by a Google developer, aptly capture this concept by asserting that a significant number of users will depend on observable behaviors, irrespective of contractual promises. Due to that:

  1. You can’t throw anything away.
  2. You can’t change the meaning.
  3. Everything what comes beyond the first publishing is optional.

In contrast to the “obligation model” (Link 7) followed in traditional development, the negotiation pattern allows each module to make promises about its own behavior. These promises can be altered or withdrawn without creating any obligations for consumers. As a result, provider and consumer modules are loosely coupled by promises, fostering flexibility and autonomy. For more technical insights, you can refer to the W3C promise guide (Link 8).

This entry was posted in Uncategorized. Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *