dclucas / web-api-changes-catalog

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

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

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

About

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