Proposed incompatible changes to the REST API
I'm considering making two small incompatible changes to the JSON representation of list requests in the REST API. Here's what you currently get (from rest/docs/moderation.rst) for a held subscription request:
>>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/requests/1')
address: anne@example.com
delivery_mode: regular
display_name: Anne Person
http_etag: "..."
language: en
password: password
request_id: 1
type: subscription
when: 2005-08-01T07:49:23I want to change the 'address' key to 'email' and remove the 'password' key, e.g.:
>>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/requests/1')
delivery_mode: regular
display_name: Anne Person
email: anne@example.com
http_etag: "..."
language: en
request_id: 1
type: subscription
when: 2005-08-01T07:49:23Unsubscription requests would just rename 'address' to 'email' (there is no 'password' key). E.g. from:
>>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/requests/2')
address: bart@example.com
http_etag: "..."
request_id: 2
type: unsubscriptionto:
>>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/requests/2')
email: bart@example.com
http_etag: "..."
request_id: 2
type: unsubscriptionI could (mostly) keep backward compatibility by just adding the 'email' key and keeping the 'address' key for now. The 'password' key is trickier because a subscription request's password is internally and randomly generated anyway, and I am going to remove this. I could keep 'password' with either the empty string or some random garbage.
I'd like to just get rid of these and break compatibility, but if it would cause pain to Postorius or other tools, I can deprecate the old names and remove them in the future.
Let me know what you think.
Cheers, -Barry
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
On 08/26/2014 11:59 PM, Barry Warsaw wrote:
I'm considering making two small incompatible changes to the JSON representation of list requests in the REST API. Here's what you currently get (from rest/docs/moderation.rst) for a held subscription request:
dump_json('http://localhost:9001/3.0/lists/ant@example.com/requests/1')
address: anne@example.com delivery_mode: regular display_name: Anne Person http_etag: "..." language: en password: password request_id: 1 type: subscription when: 2005-08-01T07:49:23
I want to change the 'address' key to 'email' and remove the 'password' key, e.g.:
[...]
I'd like to just get rid of these and break compatibility, but if it would cause pain to Postorius or other tools, I can deprecate the old names and remove them in the future.
Let me know what you think.
We're still in beta, so I think breaking backwards compatibility is justifiable (we should probably coordinate the release of the affected packages though).
If we want to make our lives a little easier we could keep the "address" and "password" properties as proxy attributes in mailman.client to minimize the risk of things breaking. At least for a while.
In the future (once we're out of beta) we could mabye just bump up the API version number in cases like that. BTW: Should the API version nr always correspond with the core's version number? Like core version 3.0.12 => "http://localhost:8001/3.0"?
Florian
-----BEGIN PGP SIGNATURE----- Version: GnuPG v1
iQEcBAEBAgAGBQJT/dSKAAoJEEceGbPdavl7lHUH/0eLV1tzfogv3MojR2TnK5DF QS4WlJLU8s+vAZQECjrRKr5kCsiruOteVG3Hm8Ts9HEiMrq4pmjvOKc/oCl3q7C2 Hgo30mm/BCW2ZD4TQ5CCz5Q4eMV5vz01f09YS8alQx57reOx6GqSgcpTJKgjVJz4 AgGBqsDH9fkf8IGRIpoqnC4qwH4W6mofITKXLVDvAv4jHnmQv/VqMn+LN48BysI+ ij/0iH7qadTPlUfvLqv8JMNBzPBgxpEEkyVFVTQcggiwRbXTZDq8IMTBZY5E2hp5 5x4WBiNGdCJp3XwVYfmTC0/VwyM6WXbYTWDkuLhhM6iczBzdpWc+EjWNyeVtKLk= =uUdq -----END PGP SIGNATURE-----
On Aug 27, 2014, at 02:52 PM, Florian Fuchs wrote:
We're still in beta, so I think breaking backwards compatibility is justifiable (we should probably coordinate the release of the affected packages though).
Cool, and yes, definitely.
If we want to make our lives a little easier we could keep the "address" and "password" properties as proxy attributes in mailman.client to minimize the risk of things breaking. At least for a while.
That sounds reasonable.
In the future (once we're out of beta) we could mabye just bump up the API version number in cases like that. BTW: Should the API version nr always correspond with the core's version number? Like core version 3.0.12 => "http://localhost:8001/3.0"?
That was my original plan. It means that within beta releases, the API would be free to change (I'm not sure /3.0.12b1 would be worth it). TBH I haven't actually tried to see what it would mean to rev the API version path component. Maybe it could insert a flag on the request that end-points could refer to if they wanted emit some different JSON, or some responder along the path could dispatch to a different end-point if needed. In theory <wink>, it seems quite doable.
I'm really hoping the falcon guys will accept my patch, or at least work with us to get restish-style dispatch working. I *really* want to switch to falcon.
Cheers, -Barry
participants (3)
-
Barry Warsaw -
Florian Fuchs -
Stephen J. Turnbull