Add functionality to list matching references (#28)

Co-authored-by: marthast <marthast@spotify.com>

Author: Lirick

src/main/java/com/spotify/github/v3/clients/GitDataClient.java

@@ -22,12 +22,14 @@
 
 import static com.google.common.collect.ImmutableMap.of;
 import static com.spotify.github.v3.clients.GitHubClient.IGNORE_RESPONSE_CONSUMER;
+import static com.spotify.github.v3.clients.GitHubClient.LIST_REFERENCES;
 import static java.lang.String.format;
 
 import com.google.common.collect.ImmutableMap;
 import com.spotify.github.v3.git.Reference;
 import com.spotify.github.v3.git.Tag;
 import java.time.Instant;
+import java.util.List;
 import java.util.concurrent.CompletableFuture;
 
 /** Reference Api client */
@@ -38,6 +40,7 @@ public class GitDataClient {
   private static final String TAG_URI = "/repos/%s/%s/git/tags/%s";
   private static final String CREATE_REFERENCE_URI = "/repos/%s/%s/git/refs";
   private static final String CREATE_REFERENCE_TAG = "/repos/%s/%s/git/tags";
+  private static final String LIST_MATCHING_REFERENCES_URI = "/repos/%s/%s/git/matching-refs/%s";
   private final GitHubClient github;
   private final String owner;
   private final String repo;
@@ -93,6 +96,16 @@ public CompletableFuture<Tag> getTag(final String tag) {
     return github.request(path, Tag.class);
   }
 
+  /**
+   * List matching references.
+   *
+   * @param ref reference name
+   */
+  public CompletableFuture<List<Reference>> listMatchingReferences(final String ref) {
+    final String path = format(LIST_MATCHING_REFERENCES_URI, owner, repo, ref);
+    return github.request(path, LIST_REFERENCES);
+  }
+
   /**
    * Create a git branch reference. It must not include the refs/heads.
    *

src/main/java/com/spotify/github/v3/clients/GitHubClient.java

@@ -30,6 +30,7 @@
 import com.spotify.github.v3.comment.Comment;
 import com.spotify.github.v3.exceptions.ReadOnlyRepositoryException;
 import com.spotify.github.v3.exceptions.RequestNotOkException;
+import com.spotify.github.v3.git.Reference;
 import com.spotify.github.v3.prs.PullRequestItem;
 import com.spotify.github.v3.repos.Branch;
 import com.spotify.github.v3.repos.CommitItem;
@@ -83,6 +84,8 @@ public class GitHubClient {
       new TypeReference<>() {};
   static final TypeReference<List<Branch>> LIST_BRANCHES =
       new TypeReference<>() {};
+  static final TypeReference<List<Reference>> LIST_REFERENCES =
+      new TypeReference<>() {};
 
   private static final String GET_ACCESS_TOKEN_URL = "app/installations/%s/access_tokens";
 

src/test/java/com/spotify/github/v3/clients/GitDataClientTest.java

@@ -22,10 +22,12 @@
 
 import static com.google.common.collect.ImmutableMap.of;
 import static com.google.common.io.Resources.getResource;
+import static com.spotify.github.v3.clients.GitHubClient.LIST_REFERENCES;
 import static java.nio.charset.Charset.defaultCharset;
 import static java.util.concurrent.CompletableFuture.completedFuture;
 import static org.hamcrest.MatcherAssert.assertThat;
 import static org.hamcrest.core.Is.is;
+import static org.hamcrest.core.StringContains.containsString;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.mock;
@@ -38,6 +40,7 @@
 import com.spotify.github.v3.git.Tag;
 import java.io.IOException;
 import java.time.Instant;
+import java.util.List;
 import java.util.concurrent.CompletableFuture;
 import org.junit.Before;
 import org.junit.Test;
@@ -83,6 +86,22 @@ public void getTag() throws Exception {
     assertThat(tag.object().type(), is("commit"));
   }
 
+  @Test
+  public void listMatchingReferences() throws Exception {
+    final CompletableFuture<List<Reference>> fixture =
+        completedFuture(json.fromJson(getFixture("reference_list.json"), LIST_REFERENCES));
+    when(github.request(
+            "/repos/someowner/somerepo/git/matching-refs/heads/feature",
+            LIST_REFERENCES))
+        .thenReturn(fixture);
+    final List<Reference> matchingReferences = gitDataClient.listMatchingReferences("heads/feature").get();
+    assertThat(matchingReferences.size(), is(2));
+    for (Reference ref : matchingReferences) {
+        assertThat(ref.ref(), containsString("heads/feature"));
+    }
+  }
+
+
   @Test
   public void createBranchReference() throws Exception {
     final CompletableFuture<Reference> fixture =

src/test/resources/com/spotify/github/v3/clients/reference_list.json

@@ -0,0 +1,22 @@
+[
+    {
+      "ref": "refs/heads/feature-a",
+      "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlLWE=",
+      "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/feature-a",
+      "object": {
+        "type": "commit",
+        "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
+        "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd"
+      }
+    },
+    {
+      "ref": "refs/heads/feature-b",
+      "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlLWI=",
+      "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/feature-b",
+      "object": {
+        "type": "commit",
+        "sha": "612077ae6dffb4d2fbd8ce0cccaa58893b07b5ac",
+        "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/612077ae6dffb4d2fbd8ce0cccaa58893b07b5ac"
+      }
+    }
+]