Ideas for the HTTP API engine improvments

[aerostitch]

the http api engine

• access the list of hosts in the cache /api/hosts
• access checks results by host /api/host/{hostName}
• access check list by host /api/host/{hostName}/checks
• access the list of checks on a host /api/checks/{hostName}
• access a check on a specific host /api/check/{hostName}/{checkName}
• access by check on all hosts /api/reports/{checkName}

[ynnt]

It looks a bit complicated to me. :)

Here's my list of endpoints:

• access all check results on all hosts : /api/checks
• access all check results on a specific host : /api/{hostName}/checks
• access specific check : /api/checks/{checkName} (however I can't imagine how could it be useful :) )
• access daemon status : /api/status

[aerostitch]

Thanks for the feedback @ynnt

Well, if you want to get the host names that are on the list when you really use the api as an api you need to have an endpoint to list them so you need to add /api/hosts to your list.

Plus, having the hostname directly on the root of the api will be way harder to code especially if you want to evolve the api, so I wouldn't use /api/{hostName}/checks to discover the check results /api/host/{hostName} seems more logical as you basically say with this endpoint: In the api I want to access an object hostthat provides the detail of an host object and in this host objects namespace I want the details of this specific {hostName}. The addition of checks at the end seems overkill if you want the check results of the host which should be the default value. (Plus it would be more coherent with your 3rd endpoint)

Also if you're looking for just a short list of checks available (if you have a ton of them), instead of having to use jq or a script to get the list, it might be handy to have just the list in 1 call hence the usage of /api/host/{hostName}/checks. I agree that it is redundant my point 3 and 4 seem redundant (/api/checks/{hostName})

/api/check/{hostName}/{checkName} could also be attached to the host object instead of the check object which would give us /api/host/{hostName}/{checkName} to access the detail of a specific check on a given hostname. I was just afraid that we would end up with a check name checks which would conflict with the endpoint /api/host/{hostName}/checks.

/api/check/{checkName} would totally make sense as it would get the check on all available hosts. Could be handy to get an overview of how the check is behaving over all the available hosts (for example to see if any of the hosts has a correct or incorrect result, or has a result at all). Like a summary.
It was what was in /api/reports/{checkName} which could be an alias. I only proposed this endpoint based on what our current internal tm-health app is providing.

I also like a lot your idea of /api/status which would totally make sense as we're moving towards applications that provide their own status endpoint. It could also include statistics about the cache (number of entries, etc)