From c95777e47638fa7483611a2a09a4b26de8e9a327 Mon Sep 17 00:00:00 2001 From: Kohsuke Kawaguchi Date: Sun, 8 Jun 2014 10:16:15 -0700 Subject: [PATCH] [FIXED JENKINS-23228] Documented this feature and integrated a newer version of Stapler. I took the opportunity to reorder the content in the section, so that the tree parameter becomes the main subject. At this point, the depth parameter should be only used in a limited circumstance, so it should be treated as such. --- changelog.html | 3 ++ core/pom.xml | 2 +- .../resources/hudson/model/Api/index.jelly | 50 +++++++++++++------ 3 files changed, 40 insertions(+), 15 deletions(-) diff --git a/changelog.html b/changelog.html index aba59531f8..5b3bb3bde1 100644 --- a/changelog.html +++ b/changelog.html @@ -58,6 +58,9 @@ Upcoming changes
  • Fixed NullPointerException caused by the uninitialized ProcessStarter environment in build wrappers (issue 20559) +
  • + Support the range notation for pagination in API + (issue 23228)
  • API changes allowing to create nested launchers (DecoratedLauncher) (issue 19454) diff --git a/core/pom.xml b/core/pom.xml index e9be9512ed..b1bf87e103 100644 --- a/core/pom.xml +++ b/core/pom.xml @@ -42,7 +42,7 @@ THE SOFTWARE. true - 1.224 + 1.226 2.5.6.SEC03 1.8.9 diff --git a/core/src/main/resources/hudson/model/Api/index.jelly b/core/src/main/resources/hudson/model/Api/index.jelly index 215b157c24..18b003dd4e 100644 --- a/core/src/main/resources/hudson/model/Api/index.jelly +++ b/core/src/main/resources/hudson/model/Api/index.jelly @@ -105,20 +105,11 @@ THE SOFTWARE.

    Controlling the amount of data you fetch

    - In all formats, the depth query parameter can be used to control the amount of data - you'll receive. The default is depth=0, but by increasing this value you can get - a lot of data by single remote API invocation (the downside is bigger bandwidth requirement.) - Compare depth=0 and depth=1 and see what the difference - is for yourself. Also note that data created by a smaller depth value is always a subset of - the data created by a bigger depth value. -

    -

    - A newer alternative is the tree query parameter. This works with any format, e.g. JSON; - is more efficient than using depth with exclude (since information - does not need to be generated on the server and then discarded); and may be easier to use, - since you need only know what elements you are looking for, rather than what you are not looking - for (which is anyway an open-ended list when plugins can contribute API elements). - The value should be a list of property names to include, with subproperties inside square braces. + + The tree query parameter allows you to explicitly specify and retrieve only + the information you are looking for, by using an XPath-ish path expression. + + The value should be a list of property names to include, with sub-properties inside square braces. Try tree=jobs[name],views[name,jobs[name]] to see just a list of jobs (only giving the name) and views (giving the name and jobs they contain). Note: for array-type properties (such as jobs in this example), @@ -126,6 +117,37 @@ THE SOFTWARE. This will be more natural for e.g. json?tree=jobs[name] anyway: the JSON writer does not do plural-to-singular mangling because arrays are represented explicitly.

    +

    + For array-type properties, a range specifier is supported. For example, tree=jobs[name]{0,10} would + retrieve the name of the first 10 jobs. The range specifier has the following variants: +

    + + +

    + Another way to retrieve more data is to use the depth=N query parameter . + This retrieves all the data up to the specified depth. + Compare depth=0 and depth=1 and see what the difference + is for yourself. Also note that data created by a smaller depth value is always a subset of + the data created by a bigger depth value. +

    +

    + Because of the size of the data, the depth parameter should really be only used to explore + what data Jenkins can return. Once you identify the data you want to retrieve, you can then come up with + the tree parameter to exactly specify the data you need. +

    -- GitLab