Türker Yıldırım

api-design

  • JSON_TABLE turns a document into rows

    Note2 min read

    A JSON array in a column can be joined against as a table, which is occasionally the right answer and is more often a sign the data wanted…

  • Versioning an API in the URL is honest and ugly

    Note2 min read

    Every API versioning scheme is a trade between visibility and purity, and the URL version is the one nobody can get wrong. The argument against URL versioning is…

  • Sparse fieldsets make the query count depend on the caller

    Note2 min read

    Letting a client choose which fields it wants is a good feature and moves the eager-loading decision from the controller to the request. Without deriving the eager loads…

  • The retry that made the outage longer

    Deep dive16 min read

    A dependency recovered and went straight back down. Every client retrying at once, in lockstep, is a load test nobody scheduled.

  • ETags, and the conditional request nobody sends

    Note2 min read

    An ETag costs nothing to emit and saves the response body only if clients actually send the conditional header back. The write side is where ETag earns its…

  • Testing what happens when the third party is down

    Deep dive10 min read

    Every test mocks a 200 and production returned a 502 with an HTML body. The happy path is the only path with coverage.

  • Problem Details, and an error format that is not invented here

    Note2 min read

    Every API invents an error envelope, and RFC 7807 is a perfectly good one that client libraries already understand. type is the field a client should branch on…

  • Two runtimes, one health check format

    Note2 min read

    A load balancer, an orchestrator and a monitoring system each want a health endpoint, and two services answering differently is two integrations. Excluding third-party dependencies is the rule…

  • The certificate that expired on a root nobody controlled

    Deep dive9 min read

    30 September, and a certificate chain that was valid on every browser we tested. The API works and three integrations do not.

  • A message schema is an API and needs versioning

    Note2 min read

    A published message has consumers you do not control, and its shape is a contract whether or not anybody wrote one down. Publishing both versions during a transition…