[2016-03-04] Official Client Libraries

We are very excited to announce officially supported clients for 5 programming languages!

These clients support 100% of our HTML to PDF API. They will be updated whenever we add new options. So you can follow the projects on GitHub to see when we make improvements.

• https://github.com/docraptor/docraptor-csharp

• https://github.com/docraptor/docraptor-java

• https://github.com/docraptor/docraptor-php

• https://github.com/docraptor/docraptor-python

• https://github.com/docraptor/docraptor-ruby

You can start using these clients today. Feedback is welcome through DocRaptor support or on GitHub Issues.

A little back story…

DocRaptor has always had an official Ruby client. But beyond that we only provided documentation on our HTTP protocol so you could write your own.

We were fortunate that many of our customers did, and even released them as open source. Almost all programming languages have clients written for DocRaptor by our wonderful customers. Without these clients, many people wouldn’t have even tried DocRaptor.

The only downside of this organic approach was a wide variety in implementation details. Particularly each one took it’s own approach for doing things like authentication or field encoding. This made it slower and more difficult to provide support and feature updates.

So last year we started prototyping a new “ideal API.” This API would use a syntax that would be compatible across a wide variety of languages. There will always be differences, but there is a lot to gain in keeping things similar.

We also wanted to sneak in some improvements that would make using the libraries easier.

• Examples should cover 95% of use cases without needing to look at the detailed API.

• Async mode should be easier to work with.

• Use exceptions so errors would be obvious when they happened.

• Increase our effectiveness in support by making options and settings consistent across languages

With that ideal API in place we started evaluating how we were going to build these clients. We’re a company of programmers, but being a great programmer in 5+ languages at the same time is hard. So it was worth a look at generating API clients with tools Swagger, grpc, etc.

As a team who lived through the dark days of WSDL, we approached this path with skepticism. Taking a step back, all we needed was a thin wrapper around an HTTP API using idiomatic code and best practices. That seemed possible. Thinking about it from that angle opened up our eyes to generated code solving this problem.

After a quick prototype, it was pretty clear Swagger would not only work, but work well. Sure, there were a few small things we would need to fix, but we this approach would save us a lot of time and achieve all our goals. Why does every API need to reinvent the wheel? This is the essence of open source brought to API clients. So we began submitting patches to swagger-codegen project, and they graciously accepted.

Meanwhile, DocRaptor continues to evolve and we add support for a new option, ignore_resource_errors. Now our use of Swagger starts paying off. In a 4 line change, we were able to add this to every client at the same time. This was exciting.

Soon, we will be able to provide clients for even more languages that Swagger supports. Let us know which languages you’d like to see next.