Why two approaches to build filtering in rest api?

Hi,

I was wondering why the rest api supports multiple approaches to filtering builds.  Is there a preferred way?  Will one be deprecated at some point?  See below for the two approaches I'm talking about.

http://teamcity:8111/httpAuth/app/rest/builds/?locator=status:SUCCESS,count:5

http://teamcity:8111/httpAuth/app/rest/builds?status=SUCCESS&count=5

Thanks,
Jay

6 comments
Comment actions Permalink

Jason,

The current view is that "&count=" is the one to go and "locator"-based approach is to be preserved. Since TeamCity 8 "&count=" will not be used withing the API when generating links and will probbaly be deprecated at some point.
However, with pre-8.0 "&count=" is still geenrated by TeamCity...

0
Comment actions Permalink

Hi Yegor,

Just to clarify since you pointed out "&count=" specifically is that "&param=<value>" is the format I should use when filtering builds, is this correct?  Also what do you mean by "&count=" will not be used within the API when generating links, can you ellaborate a little more on this?

Thanks,
Jay

0
Comment actions Permalink

Jason,

- since at least TeamCity 7.1 (probbaly the same in 7.0), both "&count=X" and "locator=...,count:X" are supported; They will continue to be supported in 8.0 and (possibly) in the several future versions;
- "&count=X" URLs are generated by TeamCity 7.1.x for prev and next links when serving pages ot items (e.g. for lists of builds);
- since TeamCity 8.0 "locator=...,count:X" approach is used for generating those links and this becomes the main and "correct" approach to use by the clients.

Actually, I am not sure that a the client API should expose "count" as all. To follow pages, "nextHref" attribute can be used without adding any custom parameters to the request.

If you do need to generate those, ensure the URL has no "count" parameter and edd ",count=X" into the locator, this should work fine.

0
Comment actions Permalink

Thanks Yegor,

Okay, right now I'm using the locator approach so since you say it will be supported for several version I may keep it but if you say "&param=value" will the approach going forward I may be inclinded to switch.

My client API doesn't will return the results returned from your api but in a ruby data structure.  It is up to the user whether or not they pass in count or not but by your recommendation I will probably remove it from my examples and put an example using the nextHref attribute.  This information helps.

Thanks,
Jay

0
Comment actions Permalink

> It is up to the user whether or not they pass in count or not but by your recommendation

A bit more high-level library can provide an iterator back to the user code instead of result array. That way all the count-related logic can be hidden inside the library which will fetch the next page as soon the the code iterates up to the previous page end. (just a thought)

0
Comment actions Permalink

Thanks for the suggestion, I might have to do something like that rather than returning an array of objects.  Enumerator objects in ruby are great for this.

0

Please sign in to leave a comment.