[pnt12]

You can have both of best worlds using BLUF: bottom line up front. I didn't read the code because it's too early to debug someone else's code, but here's an example:

These endpoints break REST conventions and will be harder to understand and maintain.

The convention is that GET /resources will list them, and POST /resources will create anew one. You can also use a path parameter to identify a resource you want to find with GET /resources/<id> or delete with DELETE /resources/<id>.

I find it useful for two reasons:

- maybe you parse the first paragraph and you have enough context to act, so you skip the second

- or you parse the first paragraph and form the big picture in your mind, and that will make it easier to dive into the details