concept change in category api

This is an excerpt from Manning's book Irresistible APIs: Designing web APIs that developers will love.
You likely use products that are incorporating APIs all the time. The share button you see on news sites and blogs uses the APIs for those social sites, like Twitter, Facebook, or LinkedIn. If you can “Sign in with Twitter,” the site you’re visiting is using Twitter’s API to identify you. This makes for a much better user experience, because you don’t need to remember more usernames and passwords and you can jump right into enjoying the system. Figure 1.1 demonstrates a website displaying several share buttons, enabling the reader to add the page to their feed in the social network. Figure 1.2 shows how an API can propagate changes to the clients so they can update their application’s guidelines.
Figure 1.1. A blog incorporating a Twitter feed as well as API functionality for sharing to multiple social networks. A widget provides buttons for each of the social networks—Google+, Twitter, LinkedIn, and Facebook—and this widget incorporates that network’s API into the site in a manner that’s easy to implement.
![]()
Figure 1.2. Example API interactions with a monitoring application. When the monitoring application detects a change, it can propagate it to a website, mobile application, SMS notification, or email.
![]()
A RESTful API is a platform that exposes data as resources on which to operate. For instance, a contact records management application might make it possible for you to interact with users, contacts, and locations. Each of these would be exposed as a resource, or object, you can interact with, whether reading or writing changes. When you create a well-designed RESTful API, developer users can create applications commonly referred to as mashups. A mashup combines multiple APIs together to create a new user experience (see figure 1.3).
API First makes a lot of sense for any company. As soon as you have more than one product, you should have a layer to protect the clients from changes on the server. Your website and mobile application should both be able to get information from the system. A well-documented interface into the system, crafted with specific use cases in mind, allows you the freedom to change things around on the back end, as long as the interface doesn’t change. You can switch out the database, add scaling, or refactor your back end entirely as long as you adhere to the documented interface. Integrated testing is easier, and the main products running on the API will, by their nature, test the integrity of the system on a regular basis through the daily use of that platform.

This is an excerpt from Manning's book The Design of Web APIs.
The Banking API evolution described in this chapter’s introduction illustrated a possible way of introducing a breaking change. The consumer crashed because of a modified data structure that became impossible to parse (a number became an object). But that’s not the only way of introducing a breaking change. Although some are pretty obvious, like this data structure modification, others are more insidious, like modifying the possible values of a property. Also, the consequences might not always be that obvious because the changes might not cause a visible error on the consumer’s side. A breaking change could even have impacts on the provider’s side. I’ll let you imagine what the consequences could be for both consumers and the provider if amount values in dollars were replaced by values in cents in the Banking API, especially for the transfer money goal.
Any modification of the interface contract of an API that can be described formally using an API description format or via textual API documentation can introduce a breaking change. This applies to output data, input data, parameters, response statuses or errors, goals and flows, and security. Knowing how to avoid breaking changes when possible and handling them gracefully when not is, therefore, critical for an API designer.
From a pure data perspective, this means that error and success feedback data should be treated equally when it comes to modifying them in order to avoid breaking changes. From a functional perspective, the second breaking change means that we cannot introduce new types of errors into existing goals or change existing ones.
Figure 9.6 Introducing breaking changes in error feedback
![]()
This example shows us an interesting thing about breaking changes, and, more specifically, about the scope of their consequences. Modifying the
typevalue has an impact that is local to the goal itself, but renamingitemstoerrorshas a more global impact. Indeed, because the error message data structure is probably the same across the whole API, this renaming might have been done not only for the transfer money goal but for all goals. That means that not a single consumer will be able to interpret the error feedback of any goal without updating its code. That’s quite a breaking change.Breaking changes with such wide impact are not limited to errors, but can happen when modifying any common feature of an API. For example, changing naming conventions for resource IDs to comply with better guidelines is a global breaking change affecting inputs and outputs. So it’s better to look twice at such modifications and apply what you learn in this chapter about avoiding breaking changes. And regarding protocol features, let’s see what could happen if we modify HTTP status codes (figure 9.7).