[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

@@ -58,6 +58,9 @@ Upcoming changes</a>
   <li class=bug>
     Fixed <code>NullPointerException</code> caused by the uninitialized <code>ProcessStarter</code> environment in build wrappers
     (<a href="https://issues.jenkins-ci.org/browse/JENKINS-20559">issue 20559</a>)
+  <li class=rfe>
+    Support the range notation for pagination in API
+    (<a href="https://issues.jenkins-ci.org/browse/JENKINS-23228">issue 23228</a>)
   <li class=rfe>
     API changes allowing to create nested launchers (<code>DecoratedLauncher</code>)
     (<a href="https://issues.jenkins-ci.org/browse/JENKINS-19454">issue 19454</a>)

core/pom.xml

@@ -42,7 +42,7 @@ THE SOFTWARE.
 
   <properties>
     <staplerFork>true</staplerFork>
-    <stapler.version>1.224</stapler.version>
+    <stapler.version>1.226</stapler.version>
     <spring.version>2.5.6.SEC03</spring.version>
     <groovy.version>1.8.9</groovy.version>
   </properties>

core/src/main/resources/hudson/model/Api/index.jelly

@@ -105,20 +105,11 @@ THE SOFTWARE.
 
       <h2>Controlling the amount of data you fetch</h2>
       <p>
-        In all formats, the <tt>depth</tt> query parameter can be used to control the amount of data
-        you'll receive. The default is <tt>depth=0</tt>, but by increasing this value you can get
-        a lot of data by single remote API invocation (the downside is bigger bandwidth requirement.)
-        Compare <a href="xml">depth=0</a> and <a href="xml?depth=1">depth=1</a> 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.
-      </p>
-      <p>
-        <a name="tree">A newer alternative is the <tt>tree</tt> query parameter.</a> This works with any format, e.g. JSON;
-        is more efficient than using <tt>depth</tt> with <tt>exclude</tt> (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 <em>not</em> 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.
+        <a name="tree" />
+        The <tt>tree</tt> 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 <a href="xml?tree=jobs[name],views[name,jobs[name]]">tree=jobs[name],views[name,jobs[name]]</a>
         to see just a list of jobs (only giving the name) and views (giving the name and jobs they contain).
         <strong>Note</strong>: for array-type properties (such as <tt>jobs</tt> in this example),
@@ -126,6 +117,37 @@ THE SOFTWARE.
         This will be more natural for e.g. <a href="json?tree=jobs[name]">json?tree=jobs[name]</a> anyway:
         the JSON writer does not do plural-to-singular mangling because arrays are represented explicitly.
       </p>
+      <p>
+        For array-type properties, a range specifier is supported. For example, <tt>tree=jobs[name]{0,10}</tt> would
+        retrieve the name of the first 10 jobs. The range specifier has the following variants:
+      </p>
+      <ul>
+        <li>
+          <b>{M,N}</b>: From the M-th element (inclusive) to the N-th element (exclusive).
+        </li>
+        <li>
+          <b>{M,}</b>: From the M-th element (inclusive) to the end.
+        </li>
+        <li>
+          <b>{,N}</b>: From the first element (inclusive) to the N-th element (exclusive). The same as {0,N}.
+        </li>
+        <li>
+          <b>{N}</b>: Just retrieve the N-th element. The same as {N,N+1}.
+        </li>
+      </ul>
+
+      <p>
+        Another way to retrieve more data is to use the <tt>depth=N</tt> query parameter .
+        This retrieves all the data up to the specified depth.
+        Compare <a href="xml">depth=0</a> and <a href="xml?depth=1">depth=1</a> 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.
+      </p>
+      <p>
+        Because of the size of the data, the <tt>depth</tt> 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 <tt>tree</tt> parameter to exactly specify the data you need.
+      </p>
 
       <st:include it="${it.bean}" page="_api.jelly" optional="true" />
     </l:main-panel>