January 2024 Summaries

In the dynamic field of API design, the use of sub-resources can introduce significant complexities, as illustrated by experiences from Rebilly and Redocly. Initially, sub-resources like customer subscriptions seemed logical but led to cumbersome processes and inefficiencies, especially when handling tasks such as subscription cancellations and reactivations. This design choice resulted in extensive restructuring efforts to address the inefficiencies. Consequently, the lesson learned was to avoid sub-resources unless absolutely necessary and to consider the full lifecycle of an entity in API design. At Redocly, a rule was implemented to detect sub-resource usage automatically, preventing potential inefficiencies from reaching production. This experience underscores the importance of thoughtful API design and encourages ongoing learning and adaptation in the field.

Aligning a team on API design standards can be challenging, especially for those new to API linting, and the Redocly recommended ruleset offers a good starting point. To support users, an API guidelines builder has been created to guide them through common decisions, resulting in a usable ruleset for linting API descriptions. The process includes a quiz tool and resources to help create and implement API guidelines effectively, with advice on facilitating successful workshop sessions. It is recommended to answer only essential questions during these sessions to avoid creating a cumbersome ruleset, and to regularly review and update the guidelines. The output from the guidelines builder can be used with Redocly CLI, and the integration of a design-first workflow ensures that high API standards are maintained. Regular evaluation and sharing of resources among team members are encouraged to continually improve API practices, with additional resources and tools available through Redocly for further learning and development.

Reflecting on 2023, Redocly experienced a year of recovery and growth following the challenges of 2022, characterized by market instability and inflation. The company capitalized on an influx of available talent, growing its team by 37% and reinvigorating its mission to make APIs a core strength for businesses. Redocly is expanding beyond its Gatsby-based developer portal to offer specialized products, Revel and Reef, tailored for external and internal API users, respectively, with a middle-ground option called Realm for hybrid needs. The company is also enhancing its technological infrastructure to be more dynamic and flexible, while broadening its focus to include developer onboarding, mock servers, and API testing. As Redocly looks toward 2024, it aims to foster growth by seeking passionate individuals to join its journey, promoting a vision of peace, health, and enhanced API capabilities, and maintaining an ongoing dialogue with its community through direct updates and reflections from its founder.