How Cloudinary’s API docs create a great developer experience
And how Scalar helps...
The first line on Cloudinary’s homepage is “Image and Video API Platform.” API is front and center as the primary way users interact with their app.
This API-focus enables Cloudinary to integrate into many more apps and use cases than other image and video tools, but it also means developers expect a world-class API experience.
A big part of that experience is the docs, tutorials, and videos helping people learn and use the API. Cloudinary shows how much you can do with these tools to make an API accessible. This post goes over their tactics.
Giving users multiple ways to get started
Every app cares about getting users onboarded and activated, and Cloudinary is no exception.
Cloudinary’s range of onboarding materials shows they know people learn differently, especially when it comes to programming. Some want a step-by-step video tutorial to walk them through building a sample app. Others just want straight access to the API. When you are trying to appeal to many types of users, you want to give many options to help them get started.
The full range of this getting started content which includes:
Quick starts: Simple tasks that teach the basics of programmatically optimizing, transforming, and managing images and video assets. These are written for both the API and SDKs.
Videos: Interactive video walkthroughs showing the core Cloudinary flows like how to upload assets, optimize images, cropping and resizing, and more.
Samples and examples: Examples with real, modifiable code you can test Cloudinary with. This provides users with an example they can edit to fit their use case.
Interactivity: The ability to test the API directly by sending requests to specific endpoints from the docs. Users can customize their requests, add their actual details, and get responses without needing to download or set up an API client or app.
By providing these options, users can self-select how they want to be taught. This helps them find a method that works for them, and makes it more likely they will succeed onboarding onto Cloudinary.
Supporting a diversity of use cases with OpenAPI
Although the getting started content is great, as users move beyond basic use cases, they fragment and become complex, but still require support.
Luckily, being API-first provides the flexibility to handle a diversity of use cases. Developers can integrate Cloudinary into their apps how they want, no pre-built components or complicated implementation patterns needed. This is awesome because it expands the potential market and user base.
To benefit from all the use cases (and help developers discover new ones), Cloudinary provides a full set of API documentation. They do this by relying on OpenAPI and Scalar. OpenAPI is a structured standard for describing APIs and Scalar uses it to display an API reference.
The great part about this combination is that OpenAPI is autogenerated, meaning Cloudinary doesn’t need to write a bunch of docs every time they add or change an endpoint. Scalar then regenerates the API reference based on the new OpenAPI document.
This enables users to discover the full range of Cloudinary’s capability and find the endpoints that fit their more complex and unique use cases.
The added benefits of OpenAPI and Scalar
Beyond covering many more use cases, the combination of OpenAPI and Scalar provide many benefits for Cloudinary and their users:
Functionality
An interactive API reference is basically an entire separate app. It requires:
An OpenAPI parser to make the data usable
A page generator for each of the endpoints
Components with each page to handle URLs, authentication, and examples
Templates for each example that need to work with specific client libraries
And all this needs to load fast, look nice, and be responsive
If teams had to do this themselves, they might default to a subpar experience: one that rapidly goes out of date, has poor performance, and doesn’t integrate with their existing website.
Scalar prevents this by making it as easy as possible to get a modern, stylish, and functional API reference. Cloudinary passes in an OpenAPI file to a script snippet and adds that to their site.
As a bonus, Cloudinary customizes Scalar using CSS selectors to fit their style and brand. Users likely won’t notice it's something they haven’t built themselves.
Interactivity
If that functionality didn’t impress you, Scalar built an entire API client into API references. This means users can send requests straight from Cloudinary’s docs, helping them get started without needing to build a sample app of their own.
Again, adding this sort of interactivity would take a significant amount of work and maintenance, but with Scalar, Cloudinary can provide this sort of best in class user experience easily.
Embracing the OpenAPI ecosystem
Scalar is just one example of a tool in the wider OpenAPI ecosystem. By standardizing on OpenAPI, Cloudinary (and its users) can benefit from all the progress happening in this ecosystem.
As an example, another tool in this ecosystem is Speakeasy which enables Cloudinary to generate client SDKs (like Python or Ruby) from an OpenAPI document. These SDKs make setting up and using Cloudinary simpler and gives another option for users with little added work for Cloudinary.
OpenAPI also helps make developers at Cloudinary more productive by:
Generating code like the SDKs mentioned above
Act as a source of truth for API functionality and purpose for internal and external stakeholders
Ensure API development best practices like consistent endpoint design and descriptions
It’s one thing to say you want to make APIs accessible, but it’s a lot of work to actually do it.
Cloudinary does a lot of this themselves, with their high quality docs and getting started guides, but also benefit from what’s being built in the OpenAPI ecosystem, like Scalar (and we’re happy to help 😎).