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

[Barry Warsaw]

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.

The 3.1 version bump happened because there was no backward compatible
way to handle the UUID as int vs hex string change required for some
JavaScript libraries.  It couldn't be autodetected in all cases.  In
general though, we've mostly be able to manage changes in a backward
compatible way.

> 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.

This problem is analogous to adding arguments to functions.  This is
usually handled in backward compatible ways in Python by appending new
arguments to the end of the parameter list and giving them default
values.  Or to use keyword-only arguments.  The analogy breaks down in
one specific case though.

> 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).

PATCH won't fail because it allows for partial representations.  PUT
does fail because it requires the entire new representation to be
included in the request (it's a complete replacement).  This is where
the analogy to function arguments break down.

I don't really know of any good way to handle this that still conforms
to REST principles.  I don't think we want to rev the API in these cases
since that'll result in a lot of version churn.

> 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?

Simon suggests:

* 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 is pretty much the criteria I've used in the past, and it works
well enough in practice except for the PUT exception.  A couple of
thoughts on how to handle this include, using PATCH in preference to
PUT, using PUT but catch any exception then fall back to PATCH, do a GET
first to get the list of keys.  None of those are great options,
although some caching might help.

Mailman's REST API is very dynamic so we don't even have a static
representation of it that can be queried.  I did a quick scan of RESTful
Web APIs (Richardson & Amundsen - my go to bible for REST design
philosophy) and didn't find a specific discussion on this topic.

Cheers,
-Barry
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: Message signed with OpenPGP
URL: <http://mail.python.org/pipermail/mailman-developers/attachments/20171228/295cced2/attachment.sig>