Designing Wonderful .NET APIs
summary
Argues concrete API rules and shows them applied to Newtonsoft.Json: follow Pit of Success, avoid Wall of Complexity, exploit the Power of Sameness. Demonstrates fixes made in JSON.NET — clearer exceptions now include the value, target type, JSON path and line/position; a contract resolver to emit camelCase; using [Obsolete] for staged removals; adding virtual members to JsonConverter for safe extension; prefer composition over inheritance; lazy constructors, fail-fast checks, and small helper methods. Notes scale: JSON.NET sits under ~10,000 NuGet packages, so stability matters.
AI-written summary · about
chapters (30)
- 0:00Introduction
- 1:45Dont API Design
- 3:23Why is API Design Important
- 3:49APIs are Forever
- 7:04Everyone is an API Designer
- 8:05What makes a good API
- 11:33Hibernate example
- 13:54API power
- 15:06API evolution
- 16:16Pit of success
- 17:50Wall of complexity
- 18:29Web Forms
- 22:38Power of Sameness
- 24:26Start Small
- 28:10Expect Mistakes
- 29:48Dont Be Afraid to Say No
- 31:10Naming Guidelines
- 32:51Avoid acronyms
- 35:25Common pitfalls
- 39:00Tips to avoid problems
- 41:14Enumerations
- 42:14Named Arguments
- 43:08Enumeration
- 44:25Helper Methods
- 45:28Properties
- 48:02Fields
- 49:15constructor design
- 50:47throwing exceptions
- 54:48designing for extensibility
- 57:43Jason Serializer
related talks
59mHow I work with JSON
42mASP .NET Basics for Experts
57mDon’t need to understand the details of .NET. Until you do
47mThink Abstract, abstracting your PowerShell code
01h 00mVersioning 1.0.1
52m10 Reasons Why we Love Some APIs and Why we Hate Some Others
35mPrinciples of Awesome APIs and How to Build Them
47mBuilding APIs your users will want to use