Better document how to match (single) objects in API requests

[julianbrost]

Our API documentation uses filters in most places, even when only filtering for a single object with a known name:

• "filter": "host.name==\"example.localdomain\"", "type": "Host" (https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#process-check-result)
• In case you want to target just a single service on a host, modify the filter like this: "filter": "host.name==\"icinga2-satellite1.localdomain\" && service.name==\"ping4\" (https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#schedule-downtime)
• "type": "Host", "filter": "host.name==\"icinga2-satellite2.localdomain\"" (https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#remove-downtime)

But there is a better method for this specific case, as hidden in another example at https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#execute-command: "type": "Service", "service": "agent!custom_service"

This is obviously the better choice for selecting a single object as (1) Icinga does not have to evaluate the filter for all objects of that type but can rather directly get the desired object and (2) does not need nested quotes that have to escaped, which is especially annoying when doing API requests by hand.

I think it would be a great improvement to rewrite the API docs such that operating on a single object is the default and filters for matching multiple objects are treated as an advanced option that you only use if you actually need that functionality.

[julianbrost]

TIL by randomly finding this in the source: it's also possible to match multiple objects by name: "type": "Host", "hosts": ["agent-1", "agent-2"]

[julianbrost]

TIL: When using host(s) and service(s), you don't even need type. You can even mix and match these (not sure if that's something we should suggest to do though). But right now, this works: "service": "master-1!no-active-checks", "hosts": ["agent-1", "agent-2"], "host": "master-1" (this affects all 4 objects)

[julianbrost]

What I just wrote in https://github.com/Icinga/icinga2/pull/9429#issuecomment-1184509840 is also relevant here:

[...], it took me until today to understand how you're supposed to read the documentation: everything in the section https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#filters affects everything in the API even though the simple filters are only used for /v1/objects in the examples and not for /v1/actions, they actually work for both.

Probably the most confusing thing here is that "filter" in "In addition to these parameters a filter must be provided." does not refer to the filter attribute (query string or JSON) but rather means that you have to use any of the filtering methods described in the linked section.

So that should probably also be incorporated into a fix for this issue (maybe this will be done by the author of #9429, so if someone wants to address this issue, check if there was any progress in that PR first).