Flotiq is simplifying API documentation and API exploration with Scalar

Flotiq Updates

Flotiq now generates API documentation using Scalar to make the docs more attractive and easier to explore.

4 min read

By Flotiq team

Flotiq is simplifying API documentation and API exploration with Scalar

Introduction

At Flotiq, we are dedicated to simplifying the lives of developers by removing barriers to the effective use of our APIs. Unlike typical headless CMS solutions, we automatically publish personalized APIs based on the content type definitions created within our system. Additionally, we offer code generation and API documentation portals, which are automatically generated for every Flotiq account, to further reduce the complexity of maintaining APIs and integrating them.

Until recently, we used ReDocly and Swagger UI to provide users with personalized API documentation, code samples, and a browser-based client that enabled interactions with the API. However, we realized that this combination did not provide the optimal developer experience. We have now fully transitioned to Scalar, a comprehensive solution that integrates both API documentation and the API client interface.

Benefits using Flotiq APIs

A quick reminder: Flotiq's core values focus on reducing the complexity of building and maintaining content APIs and increasing their adoption potential. We achieve this through several key features:

Personalized APIs
OpenAPI compatibility
Automated API documentation
SDKs integrated with your account.

Personalized APIs

Flotiq allows each organization to have its own API, published based on the specific content models defined in their account. This approach not only differentiates Flotiq from conventional headless CMS platforms but also enables customers to accelerate development and streamline system maintenance by utilizing APIs that are tailored to their specific projects. For example, if you’re building an event scheduling API - this is how you might see it in Flotiq, compared to Contentful:

Comparing Flotiq API and Contentful - your personalized content API in Flotiq is descriptive and familiar, while Contenful is using a generic approach.

OpenAPI compatibility

Our APIs are fully compliant with OpenAPI 3.0 standards, which is a significant advantage for teams. This compliance allows them to seamlessly publish their APIs using gateway solutions, integrate with numerous compatible systems, and reduce the time needed to complete their projects.

Automated API documentation

We strongly believe that some of the fundamental pieces that enable API adoption are standardization and good documentation. Our APIs are designed to adhere to the OpenAPI standards from the outset, facilitating the creation and sharing of clear, comprehensive API documentation. Initially, this documentation was powered by ReDocly and included code snippets in several popular programming languages, helping developers to quickly understand and implement the APIs.

We’ve heard numerous comments from our customers that the API documentation is an amazing feature that helps them onboard developers and share APIs across the organization in an easier way, but they were disappointed with the way the web client (Swagger UI) was integrated. The lack of seamless interaction with the API directly from the documentation hindered our ability to provide the stellar developer experience we strive for. After exploring various options, including developing our own solution, we opted for Scalar, which brought significant improvements:

API client embedded in the documentation

Embedded API client lets you work with your personalized Flotiq API immediately from the browser.

Authorization support

Integrated authorization makes it even simpler to start working.

Improved search in the API docs

Working with large APIs is now easier thanks to the improved search.

Amazing user interface (dark mode!)

Working with the API docs feels a lot better now, thanks to the dark mode.

Our upgrade to Scalar was mostly a drop-in replacement for the previous stack and also simplified our documentation generation pipeline (nice!).

Summary

In our ongoing effort to focus on developer experience and assist teams in building robust, future-proof systems, we have upgraded the API documentation section of Flotiq. Transitioning to Scalar not only improved the functionality and user experience but also opened up new possibilities for future enhancements, follow our posts and updates to be the first to learn when they land!

Share this article

...