On 12/27/2017 09:49 AM, Abhilash Raj wrote:
Core's REST API is versioned and any change that break backwards-compatibility cause the version to bump so that clients can take care of that.
However, one question that I have been thinking about recently is how to handle additions to REST API that don't necessarily break the backwards compatibility.
For example, Core added
max_message_sizeattribute to MailingList's REST endpoint, but it hasn't made into any released version yet. Also, Postorius added max_message_size in
Message Acceptancesettings. The problem here is that the entire PUT/PATCH request is going to fail if the currently running version of Core doesn't have
max_message_sizeattribute exposed (Unknown Attribute Error).
There is no easy way to check for whether the Core has this attribute as API is versioned at 3.1 for both cases.
So, how do we actually handle this and maybe future cases like this?
How about defining it this way:
- The result of queries can be viewed as dictionaries
- New endpoints (urls) can be added anytime
- No endpoint is removed without a version bump
- Existing dict keys will not be dropped without a version bump
- The format of values assigned to existing keys will not change without
a version bump
- New keys (and values) can be added anytime
This would make things like exposing new stuff easy. Clients that don't know about a field can just ignore it.