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:
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
- Authorization support
- Improved search in the API docs
- Amazing user interface (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!
.png)
