October 2022 Summaries

Flexport's Public API team, led by Senior Engineering Manager Nolan Sullivan, plays a crucial role in the company's transition to an API-first strategy, aiming to streamline global trade through technology. The team is tasked with expanding its scope to provide horizontal tooling for internal engineering teams, enhancing Flexport's API platform to be a critical asset for internal, partner, and third-party developers. This initiative supports Flexport's growth by increasing end-to-end automation for API developers and facilitating new product lines and strategic partnerships through efficient API integration. The team focuses on developing comprehensive API best practices, ensuring consistency and reliability, and fostering a superior developer experience (DevEx) that emphasizes self-service, accurate documentation, and adherence to industry standards. As Flexport evolves from a web app-focused company to a more flexible microservice architecture, the API team is transitioning to a federated model, where individual product teams own their respective APIs to ensure feature parity between public APIs and internal capabilities. Despite challenges like manual processes and defining platform responsibilities, the team is committed to delivering a world-class API experience, while also exploring new technologies such as AR and VR to enhance understanding of logistics environments.

In the blog post, the author discusses the implementation of authentication for embedded React components, specifically for delivering Speakeasy as a series of these components. The aim is to enable customers to safely embed API data into their web applications while ensuring data segmentation, manageability, and read-only access. After evaluating two options—API Keys and Access Tokens—the decision was made to use Access Tokens due to their superior flexibility and compatibility with existing authentication systems. Access Tokens, implemented as JWTs, offer enhanced security and ease of management compared to API Keys, as they are ephemeral and cannot be modified by end-users. This approach aligns with existing authentication flows and provides a more robust solution for controlling data scope and access permissions in embedded components.

In the comparison between Nivo and Recharts for building web charts, Recharts emerges as the preferred choice due to its ease of use and attractive default chart designs, despite both libraries having documentation and issue-related challenges. Nivo is praised for its aesthetics and online sandbox but criticized for its poor responsiveness, verbose interface, lack of comprehensive technical documentation, and limited community support. Conversely, Recharts offers an intuitive interface and features like synchronized tooltips, although it still suffers from documentation gaps and numerous open issues that can hinder troubleshooting. Overall, while Recharts was more suited to the author's needs, the exploration suggests that developers should consider other charting libraries as well, inviting feedback on alternatives to Recharts.

Nolan Sullivan's blog post from October 4, 2022, introduces new features of the Speakeasy SDK, highlighting its capacity to swiftly generate client-specific developer portals, which can be customized and shared with API users to facilitate troubleshooting and reduce the need for lengthy meetings. The SDK offers flexibility in managing data access by allowing the portal to expire after a customizable period. Additionally, the post mentions improvements to the OpenAPI schema differ, which now accommodates large API schemas, and an enhancement to the usage dashboards, which now auto-refresh with filter changes, as updated on September 16, 2025.

The blog post discusses the importance of the operationId in the OpenAPI specification, emphasizing its role in API documentation and tooling. Although the operationId is technically optional, omitting it can hinder the generation of documentation, SDKs, and server stubs. The post recommends treating operationId as a required field, ensuring that each is unique, case-insensitive, and only uses alphanumeric characters with simple separators like hyphens and underscores. It highlights the benefits of this approach, such as avoiding naming conflicts, enhancing readability, and providing consistency within the OpenAPI spec. Examples of good and bad operationIds are provided to illustrate the importance of maintaining unique and clear identifiers to facilitate the generation of downstream artifacts.