API formatting

[BLuedtke]

Currently, the API returns results in a pure text-based manner, with some similar formats across different handler, but without a specification for it. This makes parsing a chore.
A common formatting standard (e.g., JSON) should help make parsing easier. However, which standard to choose and how to name its fields has to be discussed still.

[BLuedtke]

First prototype for /monitor/* API implemented in linked branch (json-experiments). But clients have not been adjusted there. Also, need to check if any other APIs need changing.

[BLuedtke]

The API format rework has now evolved into a significant rewrite/reformatting of the major handler_X implementations. As I'm significantly modifying these handlers anyway, I'm fixing a few issues with them and also will improve upon some logging, locking etc. aspects. I propose then running this version in a 'dev'-like staging branch for a while, until the clients are also adapted and tested.

[BLuedtke]

To add a bit of context to the things going on in the api-and-handler-overhaul branch: I thought that, if I'm already changing most of the handlers and some related code, it'd be okay to also check a few other problems and inconsistencies. A partial summary:

• I checked all syslog calls with respect to format specifiers and correct arguments. In turn, I saw that size_t can be a problem as it is an unsigned long (64bit) on my development machine, but an unsigned int (32bit) on the raspberry pi (on the swtbahn-full at least) -> I changed usages of size_t to unsigned int where suitable. In most cases, unsigned int is a better fit anyway.
• Improved input validation and docs in interlocking and bahn_data_util implementations.
• Improved parameter validation - mostly improved the logs messages to differentiate between cases where parameters are missing entirely and cases where parameters are present but have an invalid value. This is mostly relevant for handler/endpoint functions. However, I adjusted regular input validation log messages to mostly match the log style/format.
• Renaming of some functions, especially in handler_driver, to differentiate "drive route" and "observe/monitor train that is driving along a route". Also renamed the auxilliary hashtable in interlocking.c and associated functions, as the two tables could easily be confused when using the old names.

A change I need to think about some more: In the dyn_containers_interface, I removed quite a few "const" qualifiers where (I thought) they didn't add much value (mostly happened in commit df7588d1ba04ae71ea9c7a4f29f5bf67114773e7). Looking back, I'm not sure if this was really necessary/helpful, at least for the pointers. However, I rarely see that kind of const used for pointers in practice (t_type_expl * const varname = ...) -> is there a use case that I am not seeing at the moment?

[BLuedtke]

What remains now is...

• checking that the chosen json reply structures/formats make sense (error handling consistent? appropriate replies?)
• change the clients (python + web) to be compatible with the api and testing them
• creating an actual OpenAPI specification for the API, instead of json-format specs for replies only (also: how could this work be done most efficiently?)
• thinking about how the OpenAPI spec should be made available -> wiki? doc files? But also should be served by the server itself, to make it available via an api?
• creating test scripts using, e.g., the python client, to have physical test cases for the swtbahn-cli
• merge things done in the master branch in the meantime back into here, most notably the what-board-am-I endpoint will need to be integrated.

So plenty of work left.