api-design

  • A sunset header tells a client before an email does

    RFC 8594 defines a header for announcing that a resource will stop being available, which puts the deprecation in the response rather than in somebody’s inbox. Almost no…

  • defineExpose, for the one method a parent needs

    A script setup component is closed by default, so a template ref to it exposes nothing until something is declared. Being closed by default is the correct choice…

  • client_max_body_size, and the upload that 413s

    Four separate limits govern an upload and the error message names only the one that fired, which is usually not the one you changed. The PHP limit failing…

  • Disabling an endpoint that has failed for a week

    Retrying forever against a dead endpoint is a queue that grows without bound, and disabling silently is worse than disabling loudly. The re-enable link in the email is…

  • A discriminated union beats four optional properties

    An interface where four properties are optional describes many states that cannot occur, and the type system cannot help with any of them. Narrowing on the discriminant is…

  • An SLO that survived contact with the business

    99.9% was written in a document in 2020 and had never been measured. Three teams with three definitions of “up”.

  • A deprecation with no measurement never completes

    Announcing a removal date without instrumentation means the date arrives and nobody can say whether removing it is safe. The brownout — disabling deliberately for a short window…

  • Measuring usage per API version, per client

    A deprecation cannot complete without knowing who is still calling, and an aggregate request count answers none of the questions that matter. The client identifier being a bounded…

  • Publishing your retry schedule, so nobody has to ask

    A subscriber to your webhooks needs to know how long they have to fix an outage, and the answer is usually undocumented. The total window matters more than…

  • The N+1 that was in the authorisation layer

    A policy check that loads the model’s owner, per row. 200 queries on a page with 50 items and correct eager loading.