Comparing versions of APIs

63 views
Skip to first unread message

Richard Mateosian

unread,
Apr 29, 2016, 4:23:03 AM4/29/16
to api-...@googlegroups.com
Can anyone recommend good examples of -- and good tools/techniques for -- documenting API changes from one version to the next? At the moment I'm mainly interested in Java-based APIs, but I may soon be interested in Javascript, C++, and even ActionScript.

Thanks.   ...RM.
--

Richard Mateosian <x...@pacbell.net>
Berkeley, California

Andrew B

unread,
Apr 30, 2016, 3:24:01 PM4/30/16
to API Craft
Pretty low tech, but we keep our API definitions in RAML and hold them in github.

Richard Mateosian

unread,
May 1, 2016, 8:54:12 PM5/1/16
to api-...@googlegroups.com
Thanks. That's the only response I've received, so perhaps nobody is documenting Java API changes -- or maybe nobody is changing them.  :-)   ...RM

On Sat, Apr 30, 2016 at 12:24 PM, Andrew B <abr...@gmail.com> wrote:
Pretty low tech, but we keep our API definitions in RAML and hold them in github.

mca

unread,
May 1, 2016, 9:09:12 PM5/1/16
to api-...@googlegroups.com
Richard:

in distributed systems (e.g. message-based, boundary-crossing implementations), it is an anti-pattern to change the *interface* in ways that cause breakage. 

optional adds are acceptable but redefines and removes are not.

if i MUST introduce breaking changes, i create a NEW component/interface and leave the other one alone (until -- if possible -- no more requests are handled by the "old" one and then i can 410-GONE the interface).

cheers.






--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at https://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

Andrew B

unread,
May 1, 2016, 10:37:22 PM5/1/16
to API Craft
In their guidelines, Openstack additionally state that it is OK to make a breaking change to an API when "the change is the only way to fix a security bug".

That's an interesting case, it seems bad to make breaking changes, but maybe its even worse to leave dangerous APIs available.

mca

unread,
May 1, 2016, 10:42:35 PM5/1/16
to api-...@googlegroups.com
yep - security is a good reason to *break* all the implementations out there.

- announce the security flaw
- publish a new component/interface w/ assistance on migrating (or a running proxy until consumers can write their new consumer code)
- kill the old components (ASAP)

it's basically a case where you (the API provider) confess a terrible mistake and inconvenience your API consumers in order to maintain the security of your data/users.

do that enough times, and ppl will figure out you stink at security and find another provider<g>.




Reply all
Reply to author
Forward
0 new messages