Whenever I speak with developers using Fivetran, their appreciation of our documentation always comes up. Our tireless technical writing team deserves the credit for that; their dedication to quality documentation sets a very high bar.

But we’re about to set the bar even higher with our new API reference.

Three pillars of our improved developer experience

Feedback we received on our existing documentation helped us prioritize the improvement of three key facets of the developer experience: speed to solution, time to interaction and readability.

Speed to solution

Good developers are lazy developers. When I have a problem to solve, I don’t need to understand everything about the solution; I just want to know if it works. I call this the StackOverflow development method. 

Look away now, senior engineering leaders: Copying and pasting out of StackOverflow is often a developer’s first stop in testing a solution. And, sometimes, it’s all they need. StackOverflow even devised an April Fools’ joke that (briefly) scared developers into thinking they’d have to pay to copy and paste code. You can even buy a purpose-built keyboard for the task. 

Fivetran’s APIs, though well-documented, previously offered very little to the developer trained in the fine art of copying and pasting. We wanted to change that.

Time to interaction and readability

We had put our Postman Collection together to help developers get up and running quickly. But you still needed to know how to use Postman, download and configure the collection and then customize default objects to interact with our API. We needed to simplify the process.

Readability also required our attention. Markdown is incredible (thank you, Gruber!) but proves tricky when you’re working with complex information. Our current documentation can only handle tables and their descriptions, as well as JSON highlights for request and response objects. We wanted more.

So, what’s new then?

So. Many. Things.

We’re using OpenAPI

We’ve now annotated our entire API to automatically generate OpenAPI definitions. The OpenAPI specification, a standardized way to describe APIs in JSON, powers our new API reference and is available as a direct download. OpenAPI lets us automate our generation of documentation and helps you create your own automations against our API description.

API interactions directly from the docs

By entering your API key and secret, you can now interact across the entire API directly from the API reference itself. Working from the API reference gives you the ability to create connectors, groups, destinations and transformations. If you wanted to, you could set up your entire Fivetran data pipeline from your browser.

Code snippets in top languages

We now automatically generate code snippets for all of our endpoints in Curl, Node.js, Python, Java and Go. Copy and paste your way to success!

Improved readability

With a sophisticated layout that uses the industry-standard three-column design, our new API reference improves the readability of requests, their nested configs, payloads, code highlighting and much more.

What’s next?

At Fivetran, we hold our developer documentation to the same standard as our industry-leading data pipelines. We’re constantly exploring ways to improve the developer experience, and documentation is at the forefront. Soon, you can expect even more in-depth guides that walk you through Powered by Fivetran implementations, sophisticated data orchestration, Terraform, internal data apps and more. 

Give us your feedback

What API reference guides would help you most? Does the reference’s organization streamline your workflow? Email our product team to let us know.