New versions of NationBuilder API endpoints will be added whenever we make breaking changes to the interface of our resources. Below is how our developers will determine if we need to version a new endpoint or not.
What is a breaking change for our API?
- Removing or renaming an attribute or endpoint
- Removing or renaming meta data
- Making an attribute required if it didn’t exist before or started optional (unless we provide a default value)
- Changing the routes of endpoints
- Changing the attribute type
- Changing the request/response data structure
- Removing or renaming a relationship between two resources
- Removing or renaming filters, filter operands, extra fields, and sorts
- Limiting the depth of a sideload or sidepost (for example, preventing a query like `include=signups.primary_address` after the fact)
- Changing error statuses and response codes
What is not a breaking change for our API?
- Adding attributes or endpoints
- Adding meta data
- Behavioral changes of resources that don’t impact the shape of the data (such as changing the default scope of an endpoint for performance reasons)
- Changing error messages
- Removing or changing an accepted enum attribute value
- In rare cases, returning null for a nullable attribute (or empty values depending on the attribute type for non-nullable attributes) if we decide to no longer provide this data via the API, with a best effort to inform consumers of these changes
- In rare cases, fixing erroneous bug behavior that may technically be breaking, but is behavior that allows creating bad data, with a best effort to inform consumers of these changes