December 2023 Summaries

Webhooks and callbacks are mechanisms in OpenAPI that enable asynchronous communication beyond the traditional request-response model of REST APIs. Webhooks allow an API to send real-time data to a user as soon as an event occurs, requiring the user to subscribe to the event stream and provide a URL for data reception. In contrast, callbacks enable users to specify a URL for receiving asynchronous responses to long-running API requests. OpenAPI introduced callbacks in version 3.0 in 2017 and webhooks in version 3.1 in 2021. Webhooks are defined as top-level entries in the OpenAPI schema, while callbacks use runtime expressions to resolve URLs dynamically. The blog emphasizes best practices for implementing webhooks and callbacks, such as ensuring idempotency and protecting APIs from DDoS attacks. Although OpenAPI supports asynchronous APIs, the AsyncAPI standard, which is still in early development, may offer more optimized solutions for certain use cases.

An updated TypeScript code generation target has been introduced to enhance TypeScript SDKs built on OpenAPI, leveraging TypeScript's type system, native Fetch APIs, and the Zod library for data validation. These SDKs are compatible with both browsers and servers, supporting popular JavaScript runtimes like Node.js, Bun, Deno, and React Native. Notable features include user input and server response validation, polymorphic types, multipart streaming uploads, and server-sent events. The SDKs also improve tree-shaking performance, enabling users to import specific namespaces, and provide support for streaming, arbitrary-precision decimals, and big integers. The transition from Axios to the Fetch API as the HTTP client ensures compatibility across diverse environments without third-party dependencies. Breaking changes include updated SDK file structures and a shift towards ES2020 and Node.js v18+ support. Existing users can opt into the new generator through a configuration update, while new users will automatically benefit from these advancements.