APIs evolve. New features get added, old features get deprecated, and use cases change. Sometimes API consumers stick to older features by choice, and sometimes by inertia to change. As API developers, it is important to communicate changes to the API effectively to the API consumer. This communication is less of a technical issue and more of a logistics.
Traditionally, and especially with REST APIs, the communication for changes is achieved with API versioning. When there is a change in an API, the numeric version changes according to semantic versioning. In this lesson, we will not go detailed into semantic versioning, since for GraphQL APIs, it is not as relevant.
It all depends on the consumer
Before we discuss different versioning strategies, we should note that API versioning, especially for GraphQL, is a contentious topic. There is no right universal strategy — it depends on a number of factors, and even then we make tradeoffs when deciding on a particular path.
Among everything else, when it comes to API versioning, the most deciding factor is the nature of relationship between the API consumer and the API developer. A vast majority of APIs are built and consumed by teams with close inter-personal communication — such as different teams in the same organization. If the communication is well-established, for example, with tighter release cycles, API versioning can be as simple as tied to the release cycles with changelogs communicated to all stakeholders.
As the size and complexity of teams grow, this may become harder to achieve. This is especially true for use cases at the other end of the spectrum of possibility — APIs with no guaranteed and easy communication to API consumers. A classic example is public APIs exposed to a variety of API consumers, where the key communication should happen through APIs.
