For a little while, I have been maintaining an unofficial Java client library for Recurly. I originally wrote it for Kill Bill, in order to develop the Kill Bill Recurly plugin. I really only needed a few of the API calls to implement the Kill Bill integration, but since Recurly doesn’t seem to provide an official Java binding, I continue to support it beyond my initial needs as it has been getting more and more traction.
This is the type of Open-Source project which can be quite time consuming. Besides the bugs in the code itself, a lot can happen in the integration with the closed-source API. For example, some calls can behave wildly differently depending on the specified parameters, and although Recurly does a pretty good of documenting their endpoints, certain behaviors can fall through the cracks. During a debugging session, it is sometimes difficult to narrow down on the issue: is it a problem with the client code (e.g. NPE, bad serialization) or does the code not follow the expected implementation?
I recently got a bug report from oohira regarding that type of problem: https://github.com/killbilling/recurly-java-library/issues/23.
Long story short, when trying to remove add-ons from a subscription, the following payload was sent to Recurly:
<subscription> <plan_code>plan-01</plan_code> <timeframe>now</timeframe> </subscription>
which wasn’t accepted by the servers. Luckily, oohira went further and by trial and error, he realized that the following should be sent instead:
<subscription> <plan_code>plan-01</plan_code> <timeframe>now</timeframe> <subscription_add_ons type="array"></subscription_add_ons> </subscription>
This distinction wasn’t specified in the documentation, which simply stated: The original subscription’s add-ons will be removed unless they are specified in your update subscription request.
Having this information, it was quite trivial to change the code to behave that way (and oohira found a client-side serialization bug in the process).
This type of detective work has been invaluable to get a fix in a timely manner. I do have a Recurly test tenant where I run regression suites, but since I don’t use these advanced features in the Kill Bill plugin, I am not as familiar with the API as oohira or others might be. Understanding where the issue was (code or API implementation) could have taken me much longer to fix.
Consider it for your issues. When you submit a bug report, besides providing a necessary reproducible test case, think about digging a little bit in the bug. Don’t assume everybody is as familiar as you are with the feature you are using. This will go a long way with the maintainer, and you’ll likely get a more timely response.