Add example for 'compatible' locator for agents endpoint in API documentation
I was not sure if it was better to open a defect in YouTrack or to post here, but I think that the API documentation should be updated to expose the use of the "compatible" locator when making a call to the /agents API endpoint. I left a comment on the API doc Confluence page, but I'll repeat it here:
Could you add an example for the 'compatible' agent locator? I had to dig very deep to find a reference to a working example, which turns out to be that one must use "build" and not necessarily "buildType" as the agent locator (like it was mentioned here)
Please sign in to leave a comment.
Hi,
the dev commentating the "buildType" agent locator is the main dev in charge of the REST API. It does work, I have just tested it in 2018.1 (although has an extra parenthesis at the end throwing an error). Using builds instead of build types for a locator will return compatible agents with that build, not with the current state of the configuration. While this will usually be the same, a change in the configuration might render wrong results.
Given that a locator must be passed, another option is to check the compatible agents of a given build configuration. In fact, if you simply open the "buildType" endpoint for a given build configuration, the "compatibleAgents" field will have the href attribute to the exact endpoint and query that you are looking for. Could you check whether that works for you?
Hi Denis,
you're right in saying that I misinterpreted the meaning of the "compatible" locator from the GitHub thread: I now understand that it returns the agents that are compatible with a build, not the ones compatible a build type/configuration.
However, my post was actually mainly aimed more at making sure that these concepts are documented appropriately. Nowhere in the API documentation is there a reference to either the compatible:(build:(id:XXX)) on the /build endpoint OR to the "compatibleAgents" locator on the /buildTypes endpoint that you mentioned. The only example currently in the wiki relating to agent compatibility is of the one for the /buildQueue, which can lead someone to mistakenly conclude that there is no way to get get compatible agents based on a given build/buildType (as I did for quite some time).
Please add references/examples for these various locators to the API documentation. Your customers will be glad you did.