add organizations endpoint

Author: Crim

src/main/java/org/sourcelab/buildkite/api/client/BuildkiteClient.java

@@ -32,6 +32,9 @@
 import org.sourcelab.buildkite.api.client.request.GetUserRequest;
 import org.sourcelab.buildkite.api.client.request.ListBuildsRequest;
 import org.sourcelab.buildkite.api.client.request.ListEmojisRequest;
+import org.sourcelab.buildkite.api.client.request.ListOrganizationsRequest;
+import org.sourcelab.buildkite.api.client.request.OrganizationFilters;
+import org.sourcelab.buildkite.api.client.request.OrganizationFiltersBuilder;
 import org.sourcelab.buildkite.api.client.request.PageOptions;
 import org.sourcelab.buildkite.api.client.request.PageableRequest;
 import org.sourcelab.buildkite.api.client.request.PingRequest;
@@ -41,15 +44,19 @@
 import org.sourcelab.buildkite.api.client.response.Emoji;
 import org.sourcelab.buildkite.api.client.response.ErrorResponse;
 import org.sourcelab.buildkite.api.client.response.ListBuildsResponse;
+import org.sourcelab.buildkite.api.client.response.ListOrganizationsResponse;
 import org.sourcelab.buildkite.api.client.response.MetaResponse;
+import org.sourcelab.buildkite.api.client.response.Organization;
 import org.sourcelab.buildkite.api.client.response.PageableResponse;
 import org.sourcelab.buildkite.api.client.response.PagingLinks;
 import org.sourcelab.buildkite.api.client.response.PingResponse;
 import org.sourcelab.buildkite.api.client.response.parser.ErrorResponseParser;
+import org.sourcelab.buildkite.api.client.response.parser.ListOrganizationsResponseParser;
 
 import java.io.IOException;
 import java.util.List;
 import java.util.Objects;
+import java.util.Optional;
 
 /**
  * API Client for Buildkite's REST Api.
@@ -112,6 +119,61 @@ public CurrentUserResponse getUser() throws BuildkiteException {
         return executeRequest(new GetUserRequest());
     }
 
+    /**
+     * Retrieve all Organizations accessible to the current user/API access token.
+     * Results will be paged.
+     *
+     * @return All Organizations accessible to the current user/API access token. Results
+     *         will be paged if the number of results exceeds 30.
+     * @throws BuildkiteException if API returns an error response.
+     */
+    public ListOrganizationsResponse listOrganizations() throws BuildkiteException {
+        return listOrganizations(OrganizationFilters.newBuilder());
+    }
+
+    /**
+     * Retrieve all Organizations accessible to the current user/API access token.
+     * Results will be paged.
+     *
+     * @param filters Filter criteria.
+     * @return All Organizations accessible to the current user/API access token. Results
+     *         will be paged if the number of results exceeds 30.
+     * @throws BuildkiteException if API returns an error response.
+     */
+    public ListOrganizationsResponse listOrganizations(final OrganizationFiltersBuilder filters) throws BuildkiteException {
+        Objects.requireNonNull(filters);
+        return listOrganizations(filters.build());
+    }
+
+    /**
+     * Retrieve all Organizations accessible to the current user/API access token.
+     * Results will be paged.
+     *
+     * @param filters Filter criteria.
+     * @return All Organizations accessible to the current user/API access token. Results
+     *         will be paged if the number of results exceeds 30.
+     * @throws BuildkiteException if API returns an error response.
+     */
+    public ListOrganizationsResponse listOrganizations(final OrganizationFilters filters) throws BuildkiteException {
+        Objects.requireNonNull(filters);
+        return executeRequest(new ListOrganizationsRequest(filters));
+    }
+
+    /**
+     * Retrieve specific organization via its Organization slug id.
+     *
+     * @param organizationSlugId Slug of the organization to retrieve.
+     * @return Organization matching the slug, if found.
+     * @throws BuildkiteException if API returns an error response.
+     */
+    public Optional<Organization> getOrganization(final String organizationSlugId) throws BuildkiteException {
+        Objects.requireNonNull(organizationSlugId);
+        final ListOrganizationsResponse response = listOrganizations(OrganizationFilters.newBuilder()
+                .withOrganization(organizationSlugId)
+        );
+        return response.getOrganizationBySlug(organizationSlugId);
+    }
+
     /**
      * Retrieves metadata endpoint.
      * @see <a href="https://buildkite.com/docs/apis/rest-api/meta#get-meta-information">https://buildkite.com/docs/apis/rest-api/meta#get-meta-information</a>
@@ -148,6 +210,7 @@ public ListBuildsResponse listBuilds() {
     /**
      * Retrieve all builds which match the supplied search criteria.
      *
+     * @param filtersBuilder Filter criteria.
      * @return All builds which match the supplied search criteria. Results will be paged if the number of results
      *         exceeds 30 (or the page limit specified in the search criteria).
      *
@@ -160,6 +223,7 @@ public ListBuildsResponse listBuilds(final BuildFiltersBuilder filtersBuilder) {
     /**
      * Retrieve all builds which match the supplied search criteria.
      *
+     * @param filters Filter criteria.
      * @return All builds which match the supplied search criteria. Results will be paged if the number of results
      *         exceeds 30 (or the page limit specified in the search criteria).
      *

src/main/java/org/sourcelab/buildkite/api/client/request/BuildFilters.java

@@ -27,7 +27,7 @@
 /**
  * Optional Properties to filter Builds.
  */
-public class BuildFilters {
+public class BuildFilters implements Filters {
     private final Set<String> branches;
     private final Set<String> commits;
     private final ZonedDateTime createdFrom;

src/main/java/org/sourcelab/buildkite/api/client/request/Filters.java

@@ -0,0 +1,21 @@
+package org.sourcelab.buildkite.api.client.request;
+
+/**
+ * Copyright 2023 SourceLab.org https://github.com/SourceLabOrg/Buildkite-Api-Client
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+ * persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+public interface Filters {
+    public PageOptions getPageOptions();
+}

src/main/java/org/sourcelab/buildkite/api/client/request/ListOrganizationsRequest.java

@@ -0,0 +1,69 @@
+/**
+ * Copyright 2023 SourceLab.org https://github.com/SourceLabOrg/Buildkite-Api-Client
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+ * persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package org.sourcelab.buildkite.api.client.request;
+
+import org.sourcelab.buildkite.api.client.response.ListOrganizationsResponse;
+import org.sourcelab.buildkite.api.client.response.parser.ListOrganizationsResponseParser;
+import org.sourcelab.buildkite.api.client.response.parser.ResponseParser;
+
+import java.util.Objects;
+
+public class ListOrganizationsRequest extends GetRequest<ListOrganizationsResponse> implements PageableRequest<ListOrganizationsResponse> {
+    private final OrganizationFilters filters;
+    private PageOptions pageOptions;
+
+    /**
+     * Constructor.
+     * @param filters Search Criteria.
+     */
+    public ListOrganizationsRequest(final OrganizationFilters filters) {
+        Objects.requireNonNull(filters);
+        this.filters = filters;
+        this.pageOptions = filters.getPageOptions() == null ? PageOptions.getDefault() : filters.getPageOptions();
+    }
+
+    @Override
+    public String getPath() {
+        // TODO need to urlencode these?
+        if (filters.hasOrgIdSlug()) {
+            return "/v2/organizations/" + filters.getOrgIdSlug();
+        }
+        return "/v2/organizations";
+    }
+
+    @Override
+    public RequestParameters getRequestParameters() {
+        final RequestParametersBuilder builder = RequestParameters.newBuilder();
+
+        // Paging options
+        builder.withParameter("per_page", pageOptions.getPerPage());
+        builder.withParameter("page", pageOptions.getPage());
+
+        return builder.build();
+    }
+
+    @Override
+    public ResponseParser<ListOrganizationsResponse> getResponseParser() {
+        return new ListOrganizationsResponseParser(this);
+    }
+
+    @Override
+    public void updatePageOptions(final PageOptions pageOptions) {
+        this.pageOptions = Objects.requireNonNull(pageOptions);
+    }
+}

src/main/java/org/sourcelab/buildkite/api/client/request/OrganizationFilters.java

@@ -0,0 +1,66 @@
+/**
+ * Copyright 2023 SourceLab.org https://github.com/SourceLabOrg/Buildkite-Api-Client
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+ * persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package org.sourcelab.buildkite.api.client.request;
+
+/**
+ * Optional Properties to filter Organizations.
+ */
+public class OrganizationFilters implements Filters {
+    private final PageOptions pageOptions;
+    private final String orgIdSlug;
+
+    /**
+     * Builder for {@link OrganizationFilters}.
+     * @return Builder for {@link OrganizationFilters}.
+     */
+    public static OrganizationFiltersBuilder newBuilder() {
+        return new OrganizationFiltersBuilder();
+    }
+
+    /**
+     * Constructor.
+     * Use {@link BuildFiltersBuilder} to create instances.
+     */
+    public OrganizationFilters(
+        final PageOptions pageOptions,
+        final String orgIdSlug
+    ) {
+        this.pageOptions = pageOptions == null ? PageOptions.getDefault() : pageOptions;
+        this.orgIdSlug = orgIdSlug;
+    }
+
+    public String getOrgIdSlug() {
+        return orgIdSlug;
+    }
+
+    public boolean hasOrgIdSlug() {
+        return orgIdSlug != null;
+    }
+
+    public PageOptions getPageOptions() {
+        return pageOptions;
+    }
+
+    @Override
+    public String toString() {
+        return "OrganizationFilters{"
+            + "pageOptions=" + pageOptions
+            + ", orgIdSlug='" + orgIdSlug + '\''
+            + '}';
+    }
+}

src/main/java/org/sourcelab/buildkite/api/client/request/OrganizationFiltersBuilder.java

@@ -0,0 +1,92 @@
+/**
+ * Copyright 2023 SourceLab.org https://github.com/SourceLabOrg/Buildkite-Api-Client
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+ * persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package org.sourcelab.buildkite.api.client.request;
+
+/**
+ * Builder for {@link BuildFilters}.
+ */
+public final class OrganizationFiltersBuilder {
+    private PageOptions pageOptions = null;
+    private String orgIdSlug = null;
+
+    /**
+     * Constructor.
+     */
+    public OrganizationFiltersBuilder() {
+    }
+
+    /**
+     * Set the number of results per page.
+     * @param perPage Set the number of results per page.
+     * @return BuildOrganizationFiltersBuilder for method chaining.
+     */
+    public OrganizationFiltersBuilder withPerPage(final int perPage) {
+        if (this.pageOptions == null) {
+            withPageOptions(PageOptions.getDefault());
+        }
+        return withPageOptions(new PageOptions(pageOptions.getPage(), perPage));
+    }
+
+    /**
+     * Set the page to retrieve.
+     * @param page Set the page to retrieve.
+     * @return BuildOrganizationFiltersBuilder for method chaining.
+     */
+    public OrganizationFiltersBuilder withPage(final int page) {
+        if (this.pageOptions == null) {
+            withPageOptions(PageOptions.getDefault());
+        }
+        return withPageOptions(new PageOptions(page, pageOptions.getPerPage()));
+    }
+
+    /**
+     * Apply Paging Options.
+     * @param page Set the page to retrieve.
+     * @param perPage Set the number of results per page.
+     * @return BuildOrganizationFiltersBuilder for method chaining.
+     */
+    public OrganizationFiltersBuilder withPageOptions(final int page, final int perPage) {
+        return withPageOptions(new PageOptions(page, perPage));
+    }
+
+    /**
+     * Apply Paging Options.
+     * @param pageOptions Paging options to apply.
+     * @return BuildOrganizationFiltersBuilder for method chaining.
+     */
+    public OrganizationFiltersBuilder withPageOptions(final PageOptions pageOptions) {
+        this.pageOptions = pageOptions;
+        return this;
+    }
+
+    public OrganizationFiltersBuilder withOrganization(final String orgIdSlug) {
+        this.orgIdSlug = orgIdSlug;
+        return this;
+    }
+
+    /**
+     * New OrganizationFilters instance using configured properties.
+     * @return New OrganizationFilters instance using configured properties.
+     */
+    public OrganizationFilters build() {
+        return new OrganizationFilters(
+            pageOptions,
+            orgIdSlug
+        );
+    }
+}

src/main/java/org/sourcelab/buildkite/api/client/response/ListBuildsResponse.java

@@ -72,7 +72,7 @@ public List<Build> getBuilds() {
      * The total number of builds found.
      * @return The total number of builds found.
      */
-    public int countBuilds() {
+    public int count() {
         return getBuilds().size();
     }