Merge pull request #237 from github/combined-status-pagination

Ben Lavender · Ben Lavender · commit d80ddca76e07 · 2014-06-19T18:16:08.000-05:00
Combined status pagination post and doc updates
diff --git a/content/changes/2014-06-19-combined-status-api-pagination.md b/content/changes/2014-06-19-combined-status-api-pagination.md
@@ -0,0 +1,22 @@
+---
+kind: change
+title: Pagination in the Combined Status API
+created_at: 2014-06-19
+author_name: bhuga
+---
+
+We're getting close to bringing the [Combined Status API][1] out of preview
+mode, and have just a couple of small changes to make before it's :sparkles:.
+
+First, we're now [paginating][2] combined status API calls. The combined status
+`state` field will always take all statuses into account, but we'll now only
+return 100 embedded statuses at a time.
+
+Second, we're adding a `total_count` field, mirroring the Search API. This
+count represents the number of contexts submitted for the given commit.
+
+As always, we're interested in [hearing your feedback][3].
+
+[1]: /v3/repos/statuses/#get-the-combined-status-for-a-specific-ref
+[2]: /v3/#pagination
+[3]: https://github.com/contact?form[subject]=Combined+Status+API
diff --git a/content/v3/repos/statuses.md b/content/v3/repos/statuses.md
@@ -106,11 +106,14 @@ Users with pull access can access a combined view of commit statuses for a given
 
     GET /repos/:owner/:repo/commits/:ref/status
 
-The most recent status for each context is returned (up to 25), as well as a combined
-`state`. The `state` is `pending` to start, `failure` if any status reports as
-`error` or `failure`, `pending` if any context's latest status is `pending`, and
-`success` if the latest status for all contexts is `success`. (`null` is
-considered a distinct context)
+The most recent status for each context is returned, up to 100. This field
+[paginates](/v3/#pagination) if there are over 100 contexts.
+
+Additionally, a combined `state` is returned. The `state` is one of:
+
+ * **failure** if any of the contexts report as error or failure
+ * **pending** if there are no statuses or a context is pending
+ * **success** if the latest status for all contexts is success
 
 ### Parameters
 
diff --git a/lib/resources.rb b/lib/resources.rb
@@ -1629,6 +1629,7 @@ def text_html(response, status, head = {})
       "state" => "success",
       "name"  => "octocat/Hello-World",
       "sha"   => COMMIT["sha"],
+      "total_count" => 2,
       "statuses" => [
         SIMPLE_STATUS.merge("context" => "continuous-integration/jenkins"),
         SIMPLE_STATUS.merge("context" => "security/brakeman")
