From d71bd8c3a51dd0ae56745a7ad7942297dc174e08 Mon Sep 17 00:00:00 2001 From: Michele Cereda Date: Sun, 16 Mar 2025 12:01:14 +0100 Subject: [PATCH] chore(best-practices): use explicit status codes --- knowledge base/best practices.md | 30 ++++++++++++++++++++++++------ knowledge base/peerdb.md | 2 ++ 2 files changed, 26 insertions(+), 6 deletions(-) diff --git a/knowledge base/best practices.md b/knowledge base/best practices.md index e9332c9..d888c16 100644 --- a/knowledge base/best practices.md +++ b/knowledge base/best practices.md @@ -8,7 +8,8 @@ What really worked for me personally, or in my experience. 1. [Pipelining](#pipelining) 1. [Product engineering](#product-engineering) 1. [Management](#management) -1. [Sources](#sources) +1. [Further readings](#further-readings) + 1. [Sources](#sources) ## Generic concepts @@ -17,7 +18,7 @@ What really worked for me personally, or in my experience. issues in the end. - Try to understand how something really works, may it be a technology, a tool or what else.
Try at least once to do manually what an automation would do in your place. Look at the source code of tools. Read the - _fabulous_ documentation. + _fabulous_ documentation. Check if they hide error messages behind successful responses. - Stay curious. Experiment. Learn and break things (in a sane and safe way). Dive deeper into what interests you. - Make the **informed** decision that most satisfies your **current** necessities.
There is no _perfect_ nor _correct_ solution, just different sets of tradeoff. Besides, no one will ever have all the @@ -141,16 +142,29 @@ Consider what follows for _infrastructure_ and _platform engineering_ as well. - Consider and fix users' pain points **before** adding new features.
If users are not happy with one's tool they'll try moving away from it, bringing the discussion back to the previous point in this list. -- Avoid creating mindless abstractions, like templates using variables for _all_ their attributes.
- Prefer providing one or at most a few simplified solutions that use different +- Avoid creating _effectively useless_ abstractions, like templates that use variables for _all_ their attributes.
+ Prefer providing one, or at most a few, simplified solution that use different [adapters or interfaces][what does it mean to program to interfaces?] in the background instead.
E.g., check out how [Crossplane], [Radius] and [KRO] work. +- Offer **clear** error messages and **immediate** access to them.
+ Consider leveraging different, more specific status codes for different _global_ results. E.g.: + + - Return `5` instead of `1` in UNIX to point out an executable could not find a required file. + - Return [422 Unprocessable Content] instead of [200 OK] if a request was syntactically correct, but the data it + contained was wrong. + - Return [207 Multi-Status] instead of [200 OK] if an API fulfilled a request successfully, but something in the more + global process did not quite _fully_ go as expected. ## Management - Beware the [action fallacy][the "action fallacy" tells us that the most effective leaders are unseen]. -## Sources +## Further readings + +- [Standard Exit Status Codes in Linux] +- [200 OK], [207 Multi-Status], [422 Unprocessable Content] + +### Sources Listed in order of addition: @@ -196,7 +210,7 @@ Listed in order of addition: --> -[crossplane]: https://www.crossplane.io/ +[crossplane]: kubernetes/crossplane.placeholder [editorconfig]: editorconfig.md [keep a changelog]: keep%20a%20changelog.md [kro]: kubernetes/kro.md @@ -210,6 +224,9 @@ Listed in order of addition: [the automation paradox]: the%20automation%20paradox.md +[200 ok]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/200 +[207 multi-status]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/207 +[422 unprocessable content]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/422 [5 whys]: https://www.mindtools.com/a3mi00v/5-whys [a case against "platform teams"]: https://kislayverma.com/organizations/a-case-against-platform-teams/ [amazon's leadership principles]: https://www.amazon.jobs/content/en/our-workplace/leadership-principles @@ -233,6 +250,7 @@ Listed in order of addition: [murphy's law]: https://en.wikipedia.org/wiki/Murphy%27s_law [platform teams need a delightfully different approach, not one that sucks less]: https://www.chkk.io/blog/platform-teams-different-approach [simple sabotage for software]: https://erikbern.com/2023/12/13/simple-sabotage-for-software.html +[standard exit status codes in linux]: https://www.baeldung.com/linux/status-codes [the "action fallacy" tells us that the most effective leaders are unseen]: https://bigthink.com/business/action-fallacy-most-effective-leaders-unseen/ [the 10 commandments of navigating code reviews]: https://angiejones.tech/ten-commandments-code-reviews/ [the 3-2-1 backup strategy]: https://www.backblaze.com/blog/the-3-2-1-backup-strategy/ diff --git a/knowledge base/peerdb.md b/knowledge base/peerdb.md index a84030c..37d19f7 100644 --- a/knowledge base/peerdb.md +++ b/knowledge base/peerdb.md @@ -8,6 +8,8 @@ Fast, simple, and cost effective Postgres replication. ## TL;DR +API responses hide error messages behind a `200 OK` HTTP status code as of 2025-03-14. +
Setup