I recently started looking at the Stripe APIs to add billing features to DripStat. Considering the API is Stripe’s interface, I was expecting a smooth sailing, well architected Java API to use. However, looking at the Java API docs, I couldn’t help but say something about the state of Stripe’s Java APIs.

Examples use everything except Java

It starts with the tutorial pages. There is an example in every language except… guess which one?

API that feels like Ruby/Javascript

But ignoring that, I started looking at the actual API reference docs. I stumbled across sample code like this:

Map planParams = new HashMap();
planParams.put("amount", 2000);
planParams.put("interval", "month");
planParams.put("name", "Amazing Gold Plan");
planParams.put("currency", "usd");
planParams.put("id", "gold");

Plan.create(planParams);

The ‘filling a hash map’ technique is littered throughout Stripe’s APIs. Its what you would use in weakly typed language like Ruby, Javascript, etc. Not in Java where you actually have type safety.

Here is how the above API should be:

Plan plan =
   new PlanBuilder()
       .setAmount(2000)
       .setInterval(Interval.MONTH)
       .setName("Amazing Gold Plan")
       .setCurrency(Currency.USD)
       .setId("Gold")
       .build();

Using the builder pattern makes the API type safe to use and easier to read.

Another example:

Plan p = Plan.retrieve("cpum8g");
Map updateParams = new HashMap();
updateParams.put("name", "New plan name");
p.update(updateParams);

Aside from the use of maps, it is unclear if the update() method updates the Plan object in place or returns a new, updated object.

A more elegant way is:

Plan p = Plan.retrieve("cpum8g");
Plan newPlan =
       new PlanBuilder()
         .setName("New plan name")
         .update(p);

Conclusion

This is not a critique of Stripe, the service. It is a very valuable service and should exist in every country. This is a critique of the Java API specifically. I hope this article will shed some light on it and they will improve it.

Update

Someone noticed…