[Mailman-Developers] Handling additions to REST API in client side

[Simon Hanna]

On 12/27/2017 09:49 AM, Abhilash Raj wrote:
> Hi All,
>
> 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_size` attribute to MailingList's REST
> endpoint, but it hasn't made into any released version yet. Also, Postorius
> added max_message_size in `Message Acceptance` settings. 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_size` attribute 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.