At Recurly, Christmas is arriving early this year and the winds of change are in the air.  Specifically, we are pleased to announce the imminent launch of Recurly API version 3, a next-generation API built upon Open API 3, and featuring JSON as the first class transfer format.

Additionally, we will be providing a completely new set of official client libraries, built from the ground up to expose the API via several of the most widely used programming languages.  Aside from API itself, we are also releasing a re-designed, and reformatted Developer Portal, complete with new content aimed to help you integrate with the Recurly platform faster and easier than ever.

A Brief History

Recurly API v3 was initially launched as an API exclusive to integration partners working with Recurly for 3rd party system synchronization, with a primary focus on ‘read’ requests to the platform. After several months of stable operation in production, we took it to the next level and augmented the API with ‘write’ requests, to provide it as a full offering for customer integrations. We then launched an ‘early access’ period, with participation by several existing Recurly customers, in order to polish it up before general availability.

And now it’s ready for the wild!!

Don’t Worry, Be Happy. v2 Isn’t Going Away... Yet

As excited as we are about v3, we understand that API upgrades require time and effort on your part, so if you’re already using the v2 API, rest assured that it will still be active, supported, and enhanced with new features in parallel with v3 for the foreseeable future. However, once v3  launches, it will be positioned as the ‘preferred’ API for customer integrations, with existing and newly released minor versions of v2 continuing to follow the deprecation and end of life schedule outlined here. 

With that said, read further for more details on all the awesome benefits that the v3 API has to offer, why we think it should be your first choice if you’re a new customer, and why we think the upgrade is worth the investment if you’re an existing customer.

Benefits of v3 API -- and a Few Changes

JavaScript Object Notation (JSON)

  • This means improved network and serialization / deserialization performance across the clients and API. No more XML, say hello to JSON!

Developed on Open API 3

With v3, we’ll be taking automation to the next level through: 

Automated updates to the client libraries: This enables Recurly to officially support more languages and new API features will be added to client libraries more quickly.

Automated creation of code examples: Code examples are runnable and up to date with reduced errors.

Automated creation of API reference documentation: Faster publishing times and significantly reduced inconsistencies between the API and the docs (due to human error)

Rebuilt client libraries

  • v3 will launch with client libraries available for .NET Core, Ruby, Python, Java and Node.js

    We are excited to announce that the

     

    Java and Node.js clients for v3

     

    are officially supported. We enjoyed working with the community to support the v2 Java and Node.js client libraries but we felt the time was right to officially adopt them with the launch of v3.

    The v2 client library for .NET lacked support for .NET Core. We heard your pain points, and rebuilt the .NET v3 client with Core support from the ground up.

  • With explicitly managed clients, V3 allows you to scope any request to any of your sites within the same application. You'll no longer need multiple processes or thread-scoping workarounds to call multiple sites

Fewer versions and breaking changes

  • We are only versioning on breaking changes now, which means more flexibility to provide you with features and bug fixes without upgrading.

  • v3 uses a date based versioning scheme to eliminate confusion with semantic versioning. 

v3 API Early Access 

If you don’t want to wait for the official launch of v3 in October, we have good news: You can access it now! Contact our Support team to find out how you can participate in v3 Early Access.

Redesigned and Updated Developer Hub 

With the v3 launch, we also redesigned and updated our Developer Hub. This update includes an enhanced look and feel along with a reorganized and streamlined site map and navigation. What this means is you’ll be able to find the content you need more easily! 

Additional content includes:

Getting Started Guide: A starting place for customers that are new to the Recurly platform. This guide ties together Recurly’s product documentation (docs.recurly.com) with our API reference documentation to help new customers get started quickly

Upgrade Guide: Similar to the Getting Started Guide but geared toward existing Recurly customers. Provides guidance on the differences between v2 / v3 and step-by-step actions required for migration.

The Developer Hub will continue to be updated over time with guides & cookbooks related to using Recurly API v3, Recurly.js, and Webhooks to implement specific use cases.

Next Steps

Look for more news and information when v3 and the new Developer Portal officially launch.

Â