1. 41
  1.  

  2. 24

    Re: The API pagination example:

    {
      "results": [
        {"id": 1, "name": "One"},
        {"id": 2, "name": "Two"},
        {"id": 3, "name": "Three"}
      ],
      "next_url": null
    }
    

    I’d generalize that to: never return just a list of things in a JSON response, like [1,2,3], always encapsulate in an object, like {'numbers':[1,2,3]} - the downside is a few bytes and a layer, the advantage is: you’re infinitely forward compatible, by just providing other keys than numbers.

    1. 10

      As to API design, I recently learnt about the https://aip.dev set of guidelines, and I recommend it left and right to whomever I can, seeing how it captures a lot of patterns I learnt the hard way, and many I haven’t learnt yet but now see how can be valuable. Plus a linter to help me keep them.

      And notably, API design is a place you’ll do good to have both a stronger YAGNI and a stronger “PAGNI” attitude (in various complementary ways) than in “your typical internal code” (due to backwards compatibility needs).

      1. 3

        Applies to more than just APIs. I do the same thing for data pipelines. It’s especially important when you need to save the raw response with some query context. If you stick fields in the raw data now you don’t have raw data and if you are working with third party data you might be clobbering fields that they add in the future.

        If you squint a bit it’s the same idea behind option types. Adding an encapsulating layer remove potential ambiguity.

      2. 9

        My favorite PAGNI arises when building distributed systems with message queues like Kafka or JMS is having an error or “deadletter” topic. Inevitably some messages will get into the system that cannot be processed for some reason, and you need to have a way to get them out of the main channel so they can be handled separately by a manual operator or a special consumer.

        1. 2

          A couple of mine for CLI tools / scripts:

          • “Real” argument parsing
          • A help feature, structured documentation in whatever your tooling provides
          • Something like a wrapper-with-subcommands structure
          • Handling for both stdin and files
          1. 0

            In other words, use common sense. Who would have thought?

            1. 37

              Appeals to common sense only work for intuitive and empirical phenomena. Nothing about programming is intuitive, though, and most programming methodology is non-scientific.

              In this particular example, I have heard people use “common sense” as a justification for YAGNI, a polar opposite position, which suggests that there’s nothing common or sensed about the opinion.

              1. 9

                Considering how dogmatic some developers can be, stuff like this needs to be said more often than you’d think.

                1. 7

                  Saying “use common sense” isn’t useful or informative to most people.

                  1. 4

                    Common sense is not as common as you’d think.