api-design – Page 6 – Türker Yıldırım

An anti-corruption layer for a supplier that renames fields

NoteDecember 20, 20232 min read

A supplier who renamed four response fields in a patch release, twice in two years, with the second one costing an afternoon instead of a week. The null-coalescing…

Typed class constants, and the interface that had been lying

Deep diveDecember 7, 202310 min read

8.3 on 23 November, and a constant can finally declare a type. An interface constant documented as a string, implemented as an int in one class.

An idempotency key on a POST, documented

NoteDecember 6, 20232 min read

A client that retried a timed-out payment request and created two, and no way for them to have avoided it. The conflict case is the part that has…

An error shape agreed once, and used everywhere

NoteNovember 23, 20232 min read

Four error formats across one API, because each was invented by whoever wrote that controller. RFC 7807 is a small specification and the value is not its contents…

The interface with one implementation, and when that is fine

Deep diveNovember 16, 202310 min read

140 interfaces, 128 of them with exactly one implementation, and a jump-to-definition that always lands on the wrong file.

An OpenAPI document generated from the router

NoteOctober 2, 20231 min read

A hand-written specification that had been correct in March and described four endpoints that no longer existed. Generating from the router makes drift impossible in one direction —…

A value object library, and the day it needed a serializer

Deep diveSeptember 20, 202310 min read

A Money type, an Email type, and thirty more, none of which can cross a boundary without being unwrapped by hand.

A JSON column that had become a schema

Deep diveSeptember 20, 20239 min read

A settings column with forty keys, four of which are queried, and a WHERE on a JSON path scanning two million rows.

A discriminated union instead of four optional fields

NoteSeptember 6, 20232 min read

A response type with four optional properties permits sixteen shapes, of which three are valid. The compiler now narrows on status, so the branch that reads data is…

Cursor pagination, and the offset that timed out at page 900

NoteJune 20, 20232 min read

LIMIT 50 OFFSET 45000 reads forty-five thousand rows and discards them, which is fine until somebody paginates to the end. The row-value comparison is the part that trips…