[ TOPIC ]
api-design
90 real merged PRs across 16 projects, ordered easiest to hardest. Read them in order to see how api-design shows up in production code, then go deeper with the free papers and talks below.
[ 01 // REAL PRs ]
Start here (junior) · 4
Add Pacific Time (Canada) and Alberta Time zone mappings
This PR teaches how to safely add new time zone mappings for regional changes while preserving backwards compatibility and updating tests and documentation accordingly.
fix(ui): remove kind filter from appset page (#29310)
This PR demonstrates how to conditionally hide a UI filter based on context, propagate feature flags through React components, and add targeted tests for new logic.
feat(actions): add hibernate/rehydrate actions for CNPG Cluster
This PR teaches how to add custom resource actions to a Kubernetes operator by manipulating resource annotations and surfacing them in a UI, along with corresponding tests.
code-generator: don't overwrite NegotiatedSerializer
This PR teaches a defensive programming pattern by conditionally setting a configuration field only if it is not already set, preventing unintended overwrites in client configuration.
Next (mid) · 72
🐛 Fix line splitting in `format_sse_event` to comply with SSE spec
This PR teaches how to correctly implement and test line splitting for text serialization according to a protocol spec, highlighting subtle Unicode and newline handling issues.
♻️ Update internal annotation usage for compatibilty with Pydantic 2.11
This PR teaches how subtle changes in a dependency's internal API (Pydantic) can break integration in a framework (FastAPI), and how to adapt internal usage and testing to maintain compatibility across versions.
gh-155694: Scope HTTPPasswordMgr credentials by URL scheme
This PR teaches how to scope sensitive credentials by URL scheme to prevent credential leakage between HTTP and HTTPS, illustrating secure API design and careful backwards compatibility in a widely used standard library.
Don't report unsupported types for never bound properties
This PR teaches how to correctly filter and report diagnostics in a source generator, ensuring only relevant errors are emitted for properties that are actually bound, and demonstrates how to write precise regression tests for subtle generator behaviors.
module: report unreadable package.json
This PR teaches how to handle and test for filesystem errors in module resolution, ensuring consistent error reporting when package.json files are unreadable.
tty: add raw-vt and io raw modes
This PR teaches how to extend a public API with new, explicit modes while preserving backwards compatibility and ensuring robust cross-platform testing.
Fix Environment.GetCommandLineArgs()[0] to report the host invocation name
This PR teaches how to evolve a public API to more accurately reflect platform semantics (argv[0]), while preserving backwards compatibility, handling edge cases, and updating tests to verify nuanced behavior.
Add tls-groups to control TLS named groups
This PR teaches how to safely expose and document low-level TLS configuration (named groups) in a server, handle cross-version OpenSSL compatibility, and add robust tests and documentation for a security-sensitive feature.
GH-50993: [CI][Integration] Add extension-wrapped union to integration data
This PR teaches how to design robust cross-implementation integration tests for extension types wrapping unions, and how to ensure correct type registration and buffer layout handling across serialization boundaries.
GH-50312: [Python] Fix UUID extension type round-trip to pandas returning bytes
This PR demonstrates how to add a native conversion path for a custom extension type (UUID) from Arrow to pandas, including C++/Python interop, careful API design, and comprehensive regression testing for round-trip data fidelity.
Populate PrivateMemorySize64 on macOS
This PR teaches how to design a cross-platform API that gracefully handles OS-specific limitations, surfaces platform differences in documentation, and robustly tests and reviews error-prone system interop code.
tls: throw on invalid ALPNProtocols instead of aborting
This PR teaches how to robustly validate and handle user input in a Node.js API to prevent process crashes, replacing hard aborts with recoverable exceptions and adding comprehensive tests.
🐛 Fix using `Json[list[str]]` type (issue #10997)
This PR teaches how to correctly handle and test complex typed form/query/header parameters (like Json[list[str]]) in FastAPI, including subtle error cases and robust test coverage.
feat: add `tpl` function to ApplicationSet go-templating (#16302)
This PR teaches how to safely extend a templating engine with user-defined functions (like Helm's tpl), including handling recursion limits and template option propagation to prevent crashes and inconsistent behavior.
Make `preserve_identifier_case` a three-state setting
This PR teaches how to evolve a configuration setting from a boolean to an enum for extensibility, while preserving backward compatibility and improving code clarity.
[Clang] Diagnose conflict between always_inline/noinline attributes
This PR teaches how to robustly detect and handle mutually exclusive attributes (like always_inline and noinline) in a compiler, ensuring clear diagnostics and correct attribute propagation, with thorough test coverage.
[MLIR][Analysis] Fix incorrect RegionBranchOpInterface API usage in SliceWalk
This PR teaches how to correctly use and test an interface by matching API expectations with actual data structure semantics, preventing subtle bugs from index mismatches in control-flow analysis.
Windows: add fallback if `canonicalize` fails
This PR teaches how to robustly handle platform-specific API failures by designing a fallback mechanism for Windows path canonicalization, including safe FFI, error handling, and targeted testing.
src: report libuv error when openAsBlob cannot stat
This PR teaches how to propagate and report low-level system errors accurately through an API, improving error handling and user feedback.
Fix statefulset parallel scale down
This PR teaches how to fix a subtle deadlock bug by changing processing order in a controller, improving error handling, and includes a clear regression test to verify the fix.
fs: stop stat()ing every entry in recursive readdir
This PR teaches how to optimize recursive directory reading by reducing expensive stat() calls using file type info from the OS binding, with careful error handling and API consistency.
Use Sign() to reject negative quantities in validateBasicResource
This PR teaches how to correctly validate numeric resource quantities by using a reliable sign method instead of an overflow-prone value accessor, with thorough testing and explanation.
GH-48344: [Python] Fix Table.from_struct_array for empty ChunkedArray
This PR teaches how to robustly handle edge cases in API design by ensuring correct behavior and error messages for empty or invalid inputs, and demonstrates how to write targeted regression tests for such cases.
fix(runtime-vapor): preserve vdom props normalization in interop
This PR demonstrates how to preserve prop normalization and defaulting when bridging between two component systems, with a focused regression test to ensure correct inherited prop handling and attribute filtering.
🐛 Fix support for form values with empty strings interpreted as missing (`None` if that's the default), for compatibility with HTML forms
This PR teaches how to handle subtle edge cases in form data parsing for APIs, ensuring that empty string values from HTML forms are correctly interpreted as missing (None) for optional fields, and demonstrates how to write regression tests for such cases.
custom_response: allow LocalResponsePolicy to preserve or set response_code_details
This PR demonstrates how to extend an API with new configuration options while preserving backwards compatibility and updating tests and documentation accordingly.
gh-118150: difflib: expose autojunk flag from SequenceMatcher to public methods and functions
This PR teaches how to expose a previously internal configuration parameter ('autojunk') to a module's public API while maintaining backward compatibility and updating documentation.
fix(runtime-vapor): respect inheritAttrs ownership for component roots
This PR teaches how to correctly handle attribute inheritance and fallthrough in a component framework, including how to write regression tests for subtle API contract changes.
ffi: keep FFI functions non-constructible
This PR teaches how to ensure JavaScript FFI functions are non-constructible across native and JS wrappers, highlighting subtle API design and error-prevention techniques.
GH-50801: [Python] Expose the `record_batch_reader_source` Acero node (RecordBatchReaderSourceNodeOptions)
This PR teaches how to expose a new C++ data source node to Python, including Cython bindings, Pythonic API design, and comprehensive testing of generator-backed streaming data sources.
ddl: fix wait fts ready in ddl add index
This PR teaches how to robustly handle evolving API contracts and optional fields in distributed systems, including defensive parsing, error signaling, and comprehensive testing for backward compatibility.
stream: preserve falsy cancellation reasons
This PR teaches how to correctly distinguish between 'no error' and 'falsy error values' in cancellation APIs, ensuring that all cancellation reasons (even falsy ones like 0 or '') are preserved and surfaced to consumers, and demonstrates how to write robust tests for such edge cases.
sessionctx, config: gate FK shared-lock sysvar on next-gen
This PR demonstrates how to safely gate experimental features using configuration flags, enforce them in system variable logic, and thoroughly test both configuration and system variable behavior.
[release/11.0] [System.Management] Make generated WMI wrappers disposable
This PR teaches how to safely expose resource cleanup in generated types by implementing IDisposable, and highlights the API and compatibility considerations of such a change.
Fix CrossGen2 TypeMap blob-only type references
This PR teaches how to refactor an API to handle edge cases in type resolution, especially when metadata references are missing, and highlights the importance of making required parameters explicit and robust error handling in compiler infrastructure.
feat(hydrator): add metrics to app info (#29512)
This PR demonstrates how to extend a Prometheus metric with a new label, handle nuanced state reporting, and thoroughly test and document the change for robust observability.
fix(ui): show operation state on applications list page (cherry-pick release-3.5)
This PR demonstrates how to efficiently expose just enough API data for UI needs by projecting a presence marker instead of large payloads, and how to test such minimal projections.
[compiler]: add `useWindowVirtualizer` to known incompatible libraries
This PR teaches how to maintain compatibility and safety in a compiler by explicitly marking third-party APIs as incompatible with certain optimizations due to their internal mutability patterns.
[Flang] Interface vs explicit intrinsics priority
This PR teaches how to adjust symbol resolution priority in a compiler to prefer user-defined interfaces over explicit intrinsics, including how to test such subtle language semantics changes.
[HLSL][Driver][SPIRV] Add -fspv-use-legacy-buffer-matrix-order flag
This PR demonstrates how to introduce a compiler flag for backwards compatibility, propagate it through a large codebase, and refactor built-in handling to support conditional behavior in a type-generic way.
Make LMOVEM notifications consistent with LMOVE
This PR teaches how to identify and fix inconsistent API behavior with careful coordination of documentation, backward compatibility, and regression tests.
Refactor watch event dispatch metric stage breakdown
Demonstrates a clean refactor of event dispatch metrics from hardcoded enums to a flexible timeline-based design enabling easier extension and clearer metric emission.
url: align URLPatternInit dictionary conversion with WebIDL
This PR teaches how to align a native API's dictionary conversion with WebIDL spec requirements, including property access order and omission of undefined properties, with thorough testing.
Diverse offload fixes
This PR demonstrates how to adapt macro and build system logic to support no-std environments and conditional linking, while maintaining robust test coverage for new configurations.
fix(compiler-vapor): drop comment children of Transition/TransitionGroup
This PR teaches how to align compiler output with runtime and SSR behavior by filtering out comment nodes in specific components, with comprehensive tests ensuring hydration consistency and preventing DOM mismatches.
fix: make nil DeviceTaintSelector match no devices (tracker)
This PR teaches how to correctly handle nil versus empty selectors in API logic, fix a subtle bug by aligning implementation with documented behavior, and update tests to prevent regressions.
make target feature ABI check a hard error on ARM
This PR teaches how to transition a compiler warning to a hard error for target feature ABI mismatches on ARM, including diagnostic design and targeted testing.
ai_protocol_manager: make inline string threshold configurable
This PR teaches how to expose and manage a configurable parsing threshold with fallback logic across multiple layers, including schema overrides, with validation and testing.
[flang][openmp] Support importing module declare target globals
This PR teaches how to extend compiler lowering to correctly propagate OpenMP declare target attributes for globals imported from modules, including design of modular marking functions and adding tests.
[mlir][LLVM] Preserve !associated and !absolute_symbol on llvm.mlir.global
This PR demonstrates how to extend an IR dialect and its import/export logic to preserve new metadata fields, including validation and round-trip translation between representations.
worker: add ref/unref to web workers
This PR teaches how to extend a standard API with Node.js-specific behavior using symbol-based protocols to maintain compatibility and avoid polluting the standard interface.
Implement clamp_to
This PR teaches how to design and implement a generic, const-friendly clamp_to API for ranges with careful handling of edge cases like NaN and range validity, including trait-based extensibility and unstable feature gating in Rust.
rustdoc: Take into account edition information for keyword highlighting
This PR demonstrates how to thread contextual information (like language edition) through a codebase to ensure correct feature handling and syntax highlighting, with attention to backwards compatibility and robust testing.
validation-gen: allow required/optional tags on non-pointer structs
This PR teaches how to extend validation logic to support new use cases by allowing required/optional tags on non-pointer struct fields, balancing runtime validation and documentation, with thoughtful test coverage and discussion on semantic implications.
Fix NodeRestriction audience authz fallback on volume lookup error
This PR teaches how to handle error fallback logic in authorization checks with detailed testing to ensure security correctness in a Kubernetes admission plugin.
sqlite: throw on disposal of an in-use session
This PR demonstrates how to ensure consistent error handling and state management in a native module's API, including aligning disposal and close semantics and updating tests and documentation accordingly.
implement [u8]::split_ascii_whitespace
This PR teaches how to extend a core slice API with a new iterator-based method that splits byte slices on ASCII whitespace, including designing a custom iterator, using iterator adapters, and adding comprehensive tests.
custom_response: expose existing local reply body to formatter
This PR teaches how to extend an API to expose internal data safely for custom formatting, handle precedence in configuration, and verify behavior with focused unit and integration tests.
feat: accept repository-style Azure keys in repo-creds (#29414)
This PR demonstrates how to add backwards-compatible support for multiple key aliases in configuration parsing, including precedence rules and thorough unit testing.
gh-129382: Match venv API symlink defaults to the CLI
This PR demonstrates how to align API defaults with CLI behavior in a standard library module while maintaining backwards compatibility and clear documentation.
fix(ui): show operation state on applications list page (#29063)
This PR teaches how to maintain API/UI contracts by carefully projecting only necessary fields and writing targeted tests to prevent regression in data payloads.
Rename `#[unroll]` => `#[rustc_unroll]` to mitigate nameres ambiguity
This PR teaches how to mitigate name resolution ambiguities and accidental breakage in language attribute design by renaming unstable features for backwards compatibility.
quic: convert incoming :status header to number
This PR demonstrates how to align API behavior across protocols (HTTP/2 and HTTP/3) for consistency, including updating tests and documentation to reflect subtle type changes in header handling.
[react-dom] Include all Node.js APIs in Bun entrypoint for `/server`
This PR demonstrates how to align and extend platform-specific module exports to maintain API compatibility across different JavaScript runtimes like Node.js and Bun.
Initial boilerplate for `DialectExtension`
This PR demonstrates how to scaffold a configurable system for SQL dialects, including settings, extension registration, and exposing dialects via a system table.
[SPIRV] Implement bare bones lowering for G_PREFETCH
This PR demonstrates how to conditionally lower an IR instruction to a target-specific operation or drop it based on target capabilities and extension support, illustrating careful API mapping and compatibility handling.
implement `Add` and `Sub` for `Complex`
This PR teaches how to implement generic operator overloading for a numeric type in Rust, handle trait bounds and conflicts, and write comprehensive tests for arithmetic operations.
[DOM] Update HTML parser rules for new select parser
This PR teaches how to update internal validation logic and tests to align with evolving HTML parsing standards, highlighting the importance of cross-browser consistency and developer warnings for hydration errors.
Fix misleading CRD minItems/minProperties validation errors
This PR teaches how to improve error reporting for API validation by mapping low-level validation codes to user-friendly error messages and updating tests to verify the new behavior.
dynamic_modules: expose current log level getter for HttpFilterConfigHandle in GO SDK
This PR demonstrates how to expose and test logging-related methods in SDK interfaces for better testability and API consistency across language bindings.
Revert "Add rustc_test_entrypoint_marker"
This PR teaches how to safely revert a feature that caused regressions, including handling test fallout and discussing alternative designs for attribute macros.
[libc++] Implement P3798R1: The unexpected in `std::expected`
This PR demonstrates how to add a new API method to a standard library type in a backwards-compatible way, update feature test macros, and write comprehensive tests for the change.
Go deep (senior) · 14
quic: reset rejected HTTP/3 request streams with H3_REQUEST_REJECTED
This PR teaches how to implement protocol-compliant error signaling in a networking stack, specifically how to propagate HTTP/3 request rejection codes through a QUIC implementation and expose them in a user-facing API.
JIT/Interp: Remove `MAYBENULL` TypeHandle -> RuntimeType Helper uses
This PR teaches how to refactor low-level runtime helpers by replacing special-case helper functions with inlined logic and specialized opcodes, improving clarity and performance in a complex system.
Store the names of `Fn` trait parameters in the AST, fix rustfmt bug
This PR demonstrates how to evolve a language's AST and parser to preserve more semantic information (parameter names in Fn traits), coordinating changes across the compiler, tooling, and tests while maintaining backward compatibility.
target_features: sse (or at least avx2) is incompatible with soft-float ABI
This PR teaches how to proactively handle and lint against unsupported or dangerous target feature combinations in a compiler, including the process of surfacing backend limitations to users with forward compatibility warnings.
tls: read the peer certificate chain without consuming it
This PR teaches how to fix a subtle bug involving destructive reads of TLS peer certificate chains by duplicating certificates to preserve the chain, adding a new presence check API, and includes a thorough test to ensure non-destructive repeated reads.
fix(runtime-vapor): preserve nested vdom slot content (fix #15303)
This PR demonstrates how to maintain correct slot content behavior and transition consistency when integrating two different rendering models (Vapor and VDOM) in a complex UI framework, including robust regression testing.
stabilize `c_variadic_naked_functions`
This PR teaches how language features are stabilized in a compiler, including the process of expanding ABI support for naked c-variadic functions and the careful coordination of feature gating, documentation, and backwards compatibility.
Partially support building and locating wasm proc-macros
This PR demonstrates how to extend a compiler's configuration and artifact discovery logic to support a new target (wasm proc-macros), including CLI flag design and conditional logic for experimental features.
atomic volatile: add intrinsics
This PR teaches how to extend low-level atomic intrinsics with a volatile flag across a compiler and standard library, highlighting the challenges of API evolution, cross-backend support, and the propagation of new semantics through a complex system.
support `#[target_feature(enable = ...)]` on `#[naked]` functions
Demonstrates adding support for target-specific CPU features on naked functions in a compiler backend, including cross-target handling, feature toggling, and integration with inline assembly.
[Clang] Fix a regression introduced by #216729.
This PR teaches how subtle API design choices (constructor overloads) can lead to confusing bugs in compiler internals, and how targeted tests help prevent regressions in complex language features like C++ concepts.
[clang] Fix lost lambda capture in dependent co_return operand
This PR teaches how subtle compiler semantic actions affect lambda capture correctness in dependent coroutine return expressions and how to fix them by ensuring full-expression completion.
attach global target features to module-level assembly
This PR teaches how to extend compiler backend APIs to correctly propagate target CPU features to LLVM module-level assembly, addressing subtle cross-module optimization issues and requiring coordination between Rust code and LLVM C++ bindings.
add target feature ABI checks for SPARC
This PR teaches how to add and enforce ABI consistency checks for a CPU architecture in a compiler, including updating target features, error messages, and tests to ensure correct ABI usage.
[ 03 // FREE VIDEOS & TALKS ]
Ranked by views.
other topics