Add Request Review functions (list, create, remove) (#36)

Author: vglocus

src/main/java/com/spotify/github/v3/Team.java

@@ -0,0 +1,78 @@
+/*-
+ * -\-\-
+ * github-api
+ * --
+ * Copyright (C) 2016 - 2020 Spotify AB
+ * --
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * -/-/-
+ */
+
+package com.spotify.github.v3;
+
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import com.spotify.github.GithubStyle;
+import java.net.URI;
+import javax.annotation.Nullable;
+import org.immutables.value.Value;
+
+/**
+ * Team resource represents data returned by a single Team get operation.
+ */
+@Value.Immutable
+@GithubStyle
+@JsonSerialize(as = ImmutableTeam.class)
+@JsonDeserialize(as = ImmutableTeam.class)
+public interface Team {
+
+  /** ID. */
+  @Nullable
+  Integer id();
+
+  /** Name. */
+  @Nullable
+  String name();
+
+  /** Slug. */
+  @Nullable
+  String slug();
+
+  /** Description */
+  @Nullable
+  String description();
+
+  /** Privacy */
+  @Nullable
+  String privacy();
+
+  /** Permission */
+  @Nullable
+  String permission();
+
+  /** Node ID */
+  @Nullable
+  String nodeId();
+
+  /** URL */
+  @Nullable
+  URI url();
+
+  /** HTML URL */
+  @Nullable
+  URI htmlUrl();
+
+  /** Repositories URL */
+  @Nullable
+  URI repositoriesUrl();
+}

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

@@ -32,6 +32,7 @@
 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.prs.ReviewRequests;
 import com.spotify.github.v3.repos.Branch;
 import com.spotify.github.v3.repos.CommitItem;
 import com.spotify.github.v3.repos.FolderContent;
@@ -76,6 +77,8 @@ public class GitHubClient {
   static final TypeReference<List<CommitItem>> LIST_COMMIT_TYPE_REFERENCE =
       new TypeReference<>() {};
   static final TypeReference<List<Review>> LIST_REVIEW_TYPE_REFERENCE = new TypeReference<>() {};
+  static final TypeReference<ReviewRequests> LIST_REVIEW_REQUEST_TYPE_REFERENCE =
+      new TypeReference<>() {};
   static final TypeReference<List<Status>> LIST_STATUS_TYPE_REFERENCE =
       new TypeReference<>() {};
   static final TypeReference<List<FolderContent>> LIST_FOLDERCONTENT_TYPE_REFERENCE =
@@ -493,6 +496,22 @@ CompletableFuture<Response> delete(final String path) {
     return call(request);
   }
 
+  /**
+   * Make an http DELETE request for the given path.
+   *
+   * @param path relative to the Github base url
+   * @param data request body as stringified JSON
+   * @return response body as String
+   */
+  CompletableFuture<Response> delete(final String path, final String data) {
+    final Request request =
+        requestBuilder(path)
+            .method("DELETE", RequestBody.create(parse(MediaType.APPLICATION_JSON), data))
+            .build();
+    log.debug("Making DELETE request to {}", request.url().toString());
+    return call(request);
+  }
+
   /**
    * Create a URL for a given path to this Github server.
    *
@@ -636,7 +655,7 @@ public void onResponse(final Call call, final Response response) {
 
   private RequestNotOkException mapException(final Response res, final Request request)
       throws IOException {
-    String bodyString = res.body().string();
+    String bodyString = res.body() != null ? res.body().string() : "";
     if (res.code() == FORBIDDEN) {
       if (bodyString.contains("Repository was archived so is read-only")) {
         return new ReadOnlyRepositoryException(request.url().encodedPath(), res.code(), bodyString);

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

@@ -23,6 +23,7 @@
 import static com.spotify.github.v3.clients.GitHubClient.IGNORE_RESPONSE_CONSUMER;
 import static com.spotify.github.v3.clients.GitHubClient.LIST_COMMIT_TYPE_REFERENCE;
 import static com.spotify.github.v3.clients.GitHubClient.LIST_PR_TYPE_REFERENCE;
+import static com.spotify.github.v3.clients.GitHubClient.LIST_REVIEW_REQUEST_TYPE_REFERENCE;
 import static com.spotify.github.v3.clients.GitHubClient.LIST_REVIEW_TYPE_REFERENCE;
 
 import com.google.common.base.Strings;
@@ -47,6 +48,7 @@ public class PullRequestClient {
   private static final String PR_NUMBER_TEMPLATE = "/repos/%s/%s/pulls/%s";
   private static final String PR_COMMITS_TEMPLATE = "/repos/%s/%s/pulls/%s/commits";
   private static final String PR_REVIEWS_TEMPLATE = "/repos/%s/%s/pulls/%s/reviews";
+  private static final String PR_REVIEW_REQUESTS_TEMPLATE = "/repos/%s/%s/pulls/%s/requested_reviewers";
 
   private final GitHubClient github;
   private final String owner;
@@ -173,6 +175,46 @@ public CompletableFuture<Review> createReview(final int number, final ReviewPara
     return github.post(path, jsonPayload, Review.class);
   }
 
+  /**
+   * List pull request requested reviews.
+   *
+   * @param number pull request number
+   * @return list of reviews
+   */
+  public CompletableFuture<ReviewRequests> listReviewRequests(final int number) {
+    final String path = String.format(PR_REVIEW_REQUESTS_TEMPLATE, owner, repo, number);
+    log.debug("Fetching pull request requested reviews from " + path);
+    return github.request(path, LIST_REVIEW_REQUEST_TYPE_REFERENCE);
+  }
+
+  /**
+   * Requests a review for a pull request.
+   *
+   * @param number pull request number
+   * @param properties properties for reviewing the PR, such as reviewers and team_reviewers.
+   * @see "https://docs.github.com/en/rest/reference/pulls#request-reviewers-for-a-pull-request"
+   */
+  public CompletableFuture<PullRequest> requestReview(final int number, final RequestReviewParameters properties) {
+    final String path = String.format(PR_REVIEW_REQUESTS_TEMPLATE, owner, repo, number);
+    final String jsonPayload = github.json().toJsonUnchecked(properties);
+    log.debug("Requesting reviews for PR: " + path);
+    return github.post(path, jsonPayload, PullRequest.class);
+  }
+
+  /**
+   * Remove a request for review for a pull request.
+   *
+   * @param number pull request number
+   * @param properties properties for reviewing the PR, such as reviewers and team_reviewers.
+   * @see "https://docs.github.com/en/rest/reference/pulls#request-reviewers-for-a-pull-request"
+   */
+  public CompletableFuture<Void> removeRequestedReview(final int number, final RequestReviewParameters properties) {
+    final String path = String.format(PR_REVIEW_REQUESTS_TEMPLATE, owner, repo, number);
+    final String jsonPayload = github.json().toJsonUnchecked(properties);
+    log.debug("Removing requested reviews for PR: " + path);
+    return github.delete(path, jsonPayload).thenAccept(IGNORE_RESPONSE_CONSUMER);
+  }
+
   /**
    * Merges a pull request.
    *
@@ -192,4 +234,5 @@ private CompletableFuture<List<PullRequestItem>> list(final String parameterPath
     log.debug("Fetching pull requests from " + path);
     return github.request(path, LIST_PR_TYPE_REFERENCE);
   }
+
 }

src/main/java/com/spotify/github/v3/prs/PullRequestItem.java

@@ -133,6 +133,16 @@ public interface PullRequestItem extends CloseTracking {
   @JsonProperty("_links")
   PullRequestLinks links();
 
+  /** Requested reviewers (users) */
+  @Nullable
+  @JsonProperty("requested_reviewers")
+  List<User> requestedReviewers();
+
+  /** Requested reviewers (teams) */
+  @Nullable
+  @JsonProperty("requested_teams")
+  List<User> requestedTeams();
+
   /** @Deprecated the merge commit sha. */
   Optional<String> mergeCommitSha();
 }

src/main/java/com/spotify/github/v3/prs/RequestReviewParameters.java

@@ -0,0 +1,50 @@
+/*-
+ * -\-\-
+ * github-api
+ * --
+ * Copyright (C) 2016 - 2020 Spotify AB
+ * --
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * -/-/-
+ */
+
+package com.spotify.github.v3.prs;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import com.spotify.github.GithubStyle;
+import java.util.List;
+import java.util.Optional;
+import org.immutables.value.Value;
+
+/**
+ * The parameters for requesting a review or removing review request for a Pull Request.
+ *
+ * @see "https://docs.github.com/en/rest/reference/pulls#request-reviewers-for-a-pull-request--parameters"
+ */
+@Value.Immutable
+@GithubStyle
+@JsonSerialize(as = ImmutableRequestReviewParameters.class)
+@JsonDeserialize(as = ImmutableRequestReviewParameters.class)
+@JsonInclude(JsonInclude.Include.NON_ABSENT)
+public abstract class RequestReviewParameters {
+
+    /** Request reviews from users (list of login) */
+    public abstract Optional<List<String>> reviewers();
+
+    /** Request reviews from teams (list of slugs) */
+    @JsonProperty("team_reviewers")
+    public abstract Optional<List<String>> teamReviewers();
+}

src/main/java/com/spotify/github/v3/prs/ReviewRequests.java

@@ -0,0 +1,49 @@
+/*-
+ * -\-\-
+ * github-api
+ * --
+ * Copyright (C) 2016 - 2020 Spotify AB
+ * --
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * -/-/-
+ */
+
+package com.spotify.github.v3.prs;
+
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import com.spotify.github.GithubStyle;
+import com.spotify.github.v3.User;
+import com.spotify.github.v3.Team;
+import java.util.List;
+import javax.annotation.Nullable;
+import org.immutables.value.Value;
+
+/**
+ * Pull request review resource represents data returned by a single PR review get operation. It
+ * contains all the fields from {@link Review} entity.
+ *
+ * @see https://docs.github.com/en/rest/reference/pulls#list-requested-reviewers-for-a-pull-request
+ */
+@Value.Immutable
+@GithubStyle
+@JsonSerialize(as = ImmutableReviewRequests.class)
+@JsonDeserialize(as = ImmutableReviewRequests.class)
+public interface ReviewRequests {
+
+  @Nullable
+  List<User> users();
+
+  @Nullable
+  List<Team> teams();
+}

src/test/java/com/spotify/github/v3/TeamTest.java

@@ -0,0 +1,63 @@
+/*-
+ * -\-\-
+ * github-api
+ * --
+ * Copyright (C) 2016 - 2020 Spotify AB
+ * --
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * -/-/-
+ */
+
+package com.spotify.github.v3;
+
+import static com.google.common.io.Resources.getResource;
+import static java.nio.charset.Charset.defaultCharset;
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.core.Is.is;
+
+import com.google.common.io.Resources;
+import com.spotify.github.jackson.Json;
+import java.io.IOException;
+import java.net.URI;
+import java.util.Optional;
+import org.junit.Before;
+import org.junit.Test;
+
+public class TeamTest {
+
+  private String fixture;
+
+  public static final void assertTeam(final Team team) {
+    assertThat(team.id(), is(1));
+    assertThat(team.name(), is("Justice League"));
+    assertThat(team.slug(), is("justice-league"));
+    assertThat(team.description(), is("A great team."));
+    assertThat(team.privacy(), is("closed"));
+    assertThat(team.permission(), is("admin"));
+    assertThat(team.nodeId(), is("MDQ6VGVhbTE="));
+    assertThat(team.url(), is(URI.create("https://api.github.com/teams/" + team.id())));
+    assertThat(team.htmlUrl(), is(URI.create("https://api.github.com/teams/" + team.slug())));
+    assertThat(team.repositoriesUrl(), is(URI.create(team.url() + "/repos")));
+  }
+
+  @Before
+  public void setUp() throws Exception {
+    fixture = Resources.toString(getResource(this.getClass(), "team.json"), defaultCharset());
+  }
+
+  @Test
+  public void testDeserialization() throws IOException {
+    final Team team = Json.create().fromJson(fixture, Team.class);
+    assertTeam(team);
+  }
+}