October 2025 Summaries

Designing an API involves a critical decision in choosing between a resource-first or a workflow-first approach, each having distinct implications for the API's design. The resource-first method begins with modeling domain entities as resources and implementing standard CRUD operations, offering predictability and alignment with REST principles, but it may lead to inefficiencies such as multiple calls for workflows and exposure of internal data structures. Alternatively, the workflow-first approach focuses on user needs by designing endpoints around key use cases, optimizing for usability and performance, though it requires a thorough understanding of the domain and can result in less predictable, RPC-style APIs. The most effective APIs often blend both approaches, starting with workflow considerations and validating with resources, thereby supporting efficient user workflows while maintaining a clear, resource-based structure. This hybrid approach allows for flexibility, catering to both complex workflows and simple operations, ensuring that the API is both intuitive for users and easy to evolve over time.

September 2025 brought significant updates to Redocly's product suite, emphasizing enhanced search capabilities, OpenAPI 3.2.0 support, and integration with AI through a built-in MCP server. The improvements aim to refine documentation discoverability with SEO enhancements, optimize build processes with better memory efficiency, and facilitate API documentation connection to AI assistants. Redocly has introduced basic support for OpenAPI 3.2.0 with security updates and enhanced the API testing experience with dynamic Replay configurations and persistent environments. The updates also include more flexible documentation configuration, improved GraphQL documentation control, and enhanced error handling in build pipelines. User interface enhancements, such as sidebar separator icons, aim to improve visual organization, while upcoming features include richer runtime logs, a catalog for API descriptions, and a visual workflows builder. Redocly is also expanding its team to further develop these cutting-edge tools and plans to continue investing in features that enhance performance and stability for large projects.