web-api-changes-catalog

A catalog of possible changes to a web API and their potential impact over clients.

Safe changes

Rationale for all: add-only pattern should always be safe.

change	direction
add optional field	input/output
add operation	input/output
add optional link	input/output
add resource	input/output
add optional parameter	input/output
add media type	input/output

Breaking changes

The monitorable column assumes a RESTful (or RESTful-like) API. The use of GraphQL, for example, would provide different monitoring opportunities.

Please bear in mind that monitoring alone is not a guarantee: clients may simply have not be using the breaking case during your sampling.

change	direction	monitorable?	rationale
drop default value	output	N	Null values may not be expected
drop field	output	N	Field may be under use
increase field length	output	Y	Longer length may exceed client constraint
decrease field length	input	Y	Shorter length may break input
drop constraint	output	N	Clients may rely on the constraint
add enum values	output	N	Clients may have hard-coded logic based on those values
remove enum values	input	Y	Clients may send invalid enum values
drop resource	output	Y	Clients may rely on that resource
add default value	input/output	N	Clients may expect null values
change default behavior	input/output	Y/N	Changes to default sorting, paging, etc
change status codes	input/output	Y	Clients may use response codes to handle alternate flows
change error contracts	input/output	Y	Clients may have error handling logic that relies on it
remove media type	input/output	Y	Clients may be using media type
change field format	input/output	Y/N	Client logic based on format may break, input may break
change field type	input/output	N	Structural changes will break client expectations
authorization changes	input/output	Y	Restrictint access rights may break Clients
move fields	input/output	N	Structural changes will break client expectations
add constraint	input	Y	New constraint will break client input