REST API fields parameter tutorial or documentation?

Answered

Hi,

I'm not sure if this is a REST thing or a TeamCity fields thing, but I am fascinated by the advanced usage of fields, for example, in this query:

http://buildserver/app/rest/buildTypes/?locator=project:(archived:false)&fields=$long,buildType(id,agent-requirements($long,agent-requirement($long,properties($long,$locator(name:property-name,value:env.GROOVY_HOME)))))

found in TW-45910.

specifically about the way $long and $locator are used in the fields parameter. Of course I've read the brief description in the doco, but is there a tutorial or writeup you can recommend on advanced fields usage and using the $ references in it?

 

Thanks,
Mark

2 comments
Comment actions Permalink
Official comment

Hi Mark,

Those $-values in the fields are still a bit in experimental status, so not properly documented. I am afraid there is not much additional materials about it, it's mostly examples.

Let me clarify these and feel free to ask additional questions - this will help to understand what needs to be documented.

Basically, $long is a shortcut for "all the fields" as in the dedicated entity request. It's useful when checking the response manually, but it's always better to list all the necessary fields when doing automated requests.

$locator is supported only in some places and allows to affect the filter for the nested elements. e.g. if buildType includes builds element, including builds($locator(count:10,status:SUCCESS)) into fields when requesting buildTypes will include last 10 successful builds under "builds" element.

Comment actions Permalink

Thanks for that Yegor. I look forward to when they become official; very useful additions!

Is there a good way to gather together the list of examples so far?

0

Please sign in to leave a comment.