Merge topic 'feature/projects-and-groups-apis'

91e3a2fc api/projects: add endpoint to query specific proteted_branch
524a9892 api/projects: add endpoints to query protected_branches
8f2d5bde api/groups: add endpoint to query group subgroups
547b1cb3 api/groups: add endpoint to query group projects
Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Ben Boeckel <ben.boeckel@kitware.com>
Merge-request: !249

CHANGELOG.md

@@ -7,6 +7,17 @@
     of belonging to ancestor/enclosing groups, in addition to directly added
     members.
 
+## Additions
+
+  * Added the `api::groups::projects::GroupProjects` endpoint to list a groups
+    projects.
+  * Added the `api::groups::subgroups::GroupSubgroups` endpoint to list a
+    groups subgroups.
+  * Added the `api::projects::protected_branches::ProtectedBranches` endpoint
+    to list a projects protected branches.
+  * Added the `api::projects::protected_branches::ProtectedBranch` endpoint
+    to query a projects protected branch.
+
 # v0.1301.0
 
 ## Deprecations

src/api/README.md

@@ -16,6 +16,8 @@ These API endpoints have been implemented.
   * `GET    /groups/:group/members/:id` `groups/members/member.rs`
   * `DELETE /groups/:group/members/:id` `groups/members/remove.rs`
   * `POST   /groups/:group/milestones` `groups/milestones/create.rs`
+  * `GET    /groups/:group/projects` `groups/projects/projects.rs`
+  * `GET    /groups/:group/subgroups` `groups/subgroups/subgroups.rs`
   * `GET    /projects` `projects/projects.rs`
   * `POST   /projects` `projects/projects/create.rs`
   * `GET    /projects/:project` `projects/projects/project.rs`
@@ -73,6 +75,8 @@ These API endpoints have been implemented.
   * `GET    /projects/:project/pipelines/:pipeline/variables` `projects/pipelines/variables.rs`
   * `POST   /projects/:project/protected_branches` `projects/protected_branches/protect.rs`
   * `DELETE /projects/:project/protected_branches/*branch` `projects/protected_branches/unprotect.rs`
+  * `GET    /projects/:project/protected_branches` `projects/protected_branches/protected_branches.rs`
+  * `GET    /projects/:project/protected_branches/:branch` `projects/protected_branches/protected_branch.rs`
   * `GET    /projects/:project/repository/branches` `projects/repository/branches/branches.rs`
   * `POST   /projects/:project/repository/branches` `projects/repository/branches/create.rs`
   * `GET    /projects/:project/repository/branches/:branch` `projects/repository/branches/branch.rs`
@@ -139,10 +143,8 @@ instead of having to search the page for missing endpoints.
   * `GET    /groups/:group/milestones/:milestone/burndown_events` https://gitlab.kitware.com/help/api/group_milestones.md#get-all-burndown-chart-events-for-a-single-milestone-starter
   * `GET    /groups/:group/milestones/:milestone/issues` https://gitlab.kitware.com/help/api/group_milestones.md#get-all-issues-assigned-to-a-single-milestone
   * `GET    /groups/:group/milestones/:milestone/merge_requests` https://gitlab.kitware.com/help/api/group_milestones.md#get-all-merge-requests-assigned-to-a-single-milestone
-  * `GET    /groups/:group/projects` https://gitlab.kitware.com/help/api/groups.md#list-a-groups-projects
   * `POST   /groups/:group/projects/:id` https://gitlab.kitware.com/help/api/groups.md#transfer-project-to-group
   * `POST   /groups/:group/restore` https://gitlab.kitware.com/help/api/groups.md#restore-group-marked-for-deletion-premium
-  * `GET    /groups/:group/subgroups` https://gitlab.kitware.com/help/api/groups.md#list-a-groups-subgroups
   * `DELETE /projects/:project` https://gitlab.kitware.com/help/api/projects.md#remove-project
   * `POST   /projects/:project/archive` https://gitlab.kitware.com/help/api/projects.md#archive-a-project
   * `GET    /projects/:project/commits/:sha/discussions` https://gitlab.kitware.com/help/api/discussions.md#list-project-commit-discussion-items
@@ -253,8 +255,6 @@ instead of having to search the page for missing endpoints.
   * `GET    /projects/:project/milestones/:milestone/merge_requests` https://gitlab.kitware.com/help/api/milestones.md#get-all-merge-requests-assigned-to-a-single-milestone
   * `POST   /projects/:project/milestones/:milestone/promote` https://gitlab.kitware.com/help/api/milestones.md#promote-project-milestone-to-a-group-milestone
   * `POST   /projects/:project/mirror/pull` https://gitlab.kitware.com/help/api/projects.md#start-the-pull-mirroring-process-for-a-project-starter
-  * `GET    /projects/:project/protected_branches` https://gitlab.kitware.com/help/api/protected_branches.md#list-protected-branches
-  * `GET    /projects/:project/protected_branches/:branch` https://gitlab.kitware.com/help/api/protected_branches.md#get-a-single-protected-branch-or-wildcard-protected-branch
   * `PATCH  /projects/:project/protected_branches/:branch` https://gitlab.kitware.com/help/api/protected_branches.md#require-code-owner-approvals-for-a-single-branch
   * `POST   /projects/:project/pipeline` https://gitlab.kitware.com/help/api/pipelines.md#create-a-new-pipeline
   * `GET    /projects/:project/push_rule` https://gitlab.kitware.com/help/api/projects.md#get-project-push-rules

src/api/groups.rs

@@ -15,6 +15,8 @@ mod group;
 mod groups;
 pub mod members;
 pub mod milestones;
+pub mod projects;
+pub mod subgroups;
 
 pub use create::BranchProtection;
 pub use create::CreateGroup;

src/api/groups/projects.rs

+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+//! Group projects API endpoints.
+//!
+//! These endpoints are used for querying group projects.
+
+mod projects;
+
+pub use self::projects::GroupProjects;
+pub use self::projects::GroupProjectsBuilder;
+pub use self::projects::GroupProjectsOrderBy;

src/api/groups/projects/projects.rs

+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+use derive_builder::Builder;
+
+use crate::api::common::{AccessLevel, NameOrId, SortOrder, VisibilityLevel};
+use crate::api::endpoint_prelude::*;
+use crate::api::ParamValue;
+
+/// Keys project results may be ordered by.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum GroupProjectsOrderBy {
+    /// Order by the user ID.
+    Id,
+    /// Order by the user display name.
+    Name,
+    /// Order by the path.
+    Path,
+    /// Order by the creation date of the project.
+    CreatedAt,
+    /// Order by the last updated date of the project.
+    UpdatedAt,
+    /// Order by the last activity date of the project.
+    LastActivityAt,
+}
+
+impl Default for GroupProjectsOrderBy {
+    fn default() -> Self {
+        GroupProjectsOrderBy::CreatedAt
+    }
+}
+
+impl GroupProjectsOrderBy {
+    /// The ordering as a query parameter.
+    fn as_str(self) -> &'static str {
+        match self {
+            GroupProjectsOrderBy::Id => "id",
+            GroupProjectsOrderBy::Name => "name",
+            GroupProjectsOrderBy::Path => "path",
+            GroupProjectsOrderBy::CreatedAt => "created_at",
+            GroupProjectsOrderBy::UpdatedAt => "updated_at",
+            GroupProjectsOrderBy::LastActivityAt => "last_activity_at",
+        }
+    }
+}
+
+impl ParamValue<'static> for GroupProjectsOrderBy {
+    fn as_value(self) -> Cow<'static, str> {
+        self.as_str().into()
+    }
+}
+
+/// Query projects of a group.
+#[derive(Debug, Clone, Builder)]
+#[builder(setter(strip_option))]
+pub struct GroupProjects<'a> {
+    /// The group to query for projects.
+    #[builder(setter(into))]
+    group: NameOrId<'a>,
+
+    /// Limit by archived status.
+    #[builder(default)]
+    archived: Option<bool>,
+    /// Limit by visibility public, internal, or private
+    #[builder(default)]
+    visibility: Option<VisibilityLevel>,
+
+    /// Return projects ordered by keys.
+    #[builder(default)]
+    order_by: Option<GroupProjectsOrderBy>,
+    /// Return projects sorted in asc or desc order.
+    #[builder(default)]
+    sort: Option<SortOrder>,
+    /// Search for projects using a query string.
+    ///
+    /// The search query will be escaped automatically.
+    #[builder(setter(into), default)]
+    search: Option<Cow<'a, str>>,
+
+    /// Return only the ID, URL, name, and path of each project.
+    #[builder(default)]
+    simple: Option<bool>,
+    /// Limit by projects owned by the current user.
+    #[builder(default)]
+    owned: Option<bool>,
+    /// Limit by projects starred by the current user.
+    #[builder(default)]
+    starred: Option<bool>,
+    /// Limit by projects with issues feature enabled.
+    #[builder(default)]
+    with_issues_enabled: Option<bool>,
+    /// Limit by projects with merge requests feature enabled.
+    #[builder(default)]
+    with_merge_requests_enabled: Option<bool>,
+    /// Include projects shared to this group.
+    #[builder(default)]
+    with_shared: Option<bool>,
+    /// Include projects in subgroups of this group.
+    #[builder(default)]
+    include_subgroups: Option<bool>,
+    /// Limit to projects where current user has at least this access level.
+    #[builder(default)]
+    min_access_level: Option<AccessLevel>,
+    /// Include custom attributes in response (admins only).
+    #[builder(default)]
+    with_custom_attributes: Option<bool>,
+    /// Return only projects that have security reports artifacts present in any of their builds.
+    #[builder(default)]
+    with_security_reports: Option<bool>,
+}
+
+impl<'a> GroupProjects<'a> {
+    /// Create a builder for the endpoint.
+    pub fn builder() -> GroupProjectsBuilder<'a> {
+        GroupProjectsBuilder::default()
+    }
+}
+
+impl<'a> Endpoint for GroupProjects<'a> {
+    fn method(&self) -> Method {
+        Method::GET
+    }
+
+    fn endpoint(&self) -> Cow<'static, str> {
+        format!("groups/{}/projects", self.group).into()
+    }
+
+    fn parameters(&self) -> QueryParams {
+        let mut params = QueryParams::default();
+
+        params
+            .push_opt("archived", self.archived)
+            .push_opt("visibility", self.visibility)
+            .push_opt("order_by", self.order_by)
+            .push_opt("sort", self.sort)
+            .push_opt("search", self.search.as_ref())
+            .push_opt("simple", self.simple)
+            .push_opt("owned", self.owned)
+            .push_opt("starred", self.starred)
+            .push_opt("with_issues_enabled", self.with_issues_enabled)
+            .push_opt(
+                "with_merge_requests_enabled",
+                self.with_merge_requests_enabled,
+            )
+            .push_opt("with_shared", self.with_shared)
+            .push_opt("include_subgroups", self.include_subgroups)
+            .push_opt(
+                "min_access_level",
+                self.min_access_level.map(AccessLevel::as_u64),
+            )
+            .push_opt("with_custom_attributes", self.with_custom_attributes)
+            .push_opt("with_security_reports", self.with_security_reports);
+
+        params
+    }
+}
+
+impl<'a> Pageable for GroupProjects<'a> {}
+
+#[cfg(test)]
+mod tests {
+    use crate::api::common::{AccessLevel, SortOrder, VisibilityLevel};
+    use crate::api::groups::projects::{GroupProjects, GroupProjectsOrderBy};
+    use crate::api::{self, Query};
+    use crate::test::client::{ExpectedUrl, SingleTestClient};
+
+    #[test]
+    fn order_by_default() {
+        assert_eq!(
+            GroupProjectsOrderBy::default(),
+            GroupProjectsOrderBy::CreatedAt
+        );
+    }
+
+    #[test]
+    fn order_by_as_str() {
+        let items = &[
+            (GroupProjectsOrderBy::Id, "id"),
+            (GroupProjectsOrderBy::Name, "name"),
+            (GroupProjectsOrderBy::Path, "path"),
+            (GroupProjectsOrderBy::CreatedAt, "created_at"),
+            (GroupProjectsOrderBy::UpdatedAt, "updated_at"),
+            (GroupProjectsOrderBy::LastActivityAt, "last_activity_at"),
+        ];
+
+        for (i, s) in items {
+            assert_eq!(i.as_str(), *s);
+        }
+    }
+
+    #[test]
+    fn group_is_needed() {
+        let err = GroupProjects::builder().build().unwrap_err();
+        assert_eq!(err, "`group` must be initialized");
+    }
+
+    #[test]
+    fn group_is_sufficient() {
+        GroupProjects::builder().group(1).build().unwrap();
+    }
+
+    #[test]
+    fn endpoint() {
+        let endpoint = ExpectedUrl::builder()
+            .endpoint("groups/group%2Fsubgroup/projects")
+            .build()
+            .unwrap();
+        let client = SingleTestClient::new_raw(endpoint, "");
+
+        let endpoint = GroupProjects::builder()
+            .group("group/subgroup")
+            .build()
+            .unwrap();
+        api::ignore(endpoint).query(&client).unwrap();
+    }
+
+    #[test]
+    fn endpoint_archived() {
+        let endpoint = ExpectedUrl::builder()
+            .endpoint("groups/group%2Fsubgroup/projects")
+            .add_query_params(&[("archived", "true")])
+            .build()
+            .unwrap();
+        let client = SingleTestClient::new_raw(endpoint, "");
+
+        let endpoint = GroupProjects::builder()
+            .group("group/subgroup")
+            .archived(true)
+            .build()
+            .unwrap();
+        api::ignore(endpoint).query(&client).unwrap();
+    }
+
+    #[test]
+    fn endpoint_visibility() {
+        let endpoint = ExpectedUrl::builder()
+            .endpoint("groups/group%2Fsubgroup/projects")
+            .add_query_params(&[("visibility", "private")])
+            .build()
+            .unwrap();
+        let client = SingleTestClient::new_raw(endpoint, "");
+
+        let endpoint = GroupProjects::builder()
+            .group("group/subgroup")
+            .visibility(VisibilityLevel::Private)
+            .build()
+            .unwrap();
+        api::ignore(endpoint).query(&client).unwrap();
+    }
+
+    #[test]
+    fn endpoint_order_by() {
+        let endpoint = ExpectedUrl::builder()
+            .endpoint("groups/group%2Fsubgroup/projects")
+            .add_query_params(&[("order_by", "id")])
+            .build()
+            .unwrap();
+        let client = SingleTestClient::new_raw(endpoint, "");
+
+        let endpoint = GroupProjects::builder()
+            .group("group/subgroup")
+            .order_by(GroupProjectsOrderBy::Id)
+            .build()
+            .unwrap();
+        api::ignore(endpoint).query(&client).unwrap();
+    }
+
+    #[test]
+    fn endpoint_sort() {
+        let endpoint = ExpectedUrl::builder()
+            .endpoint("groups/group%2Fsubgroup/projects")
+            .add_query_params(&[("sort", "asc")])
+            .build()
+            .unwrap();
+        let client = SingleTestClient::new_raw(endpoint, "");
+
+        let endpoint = GroupProjects::builder()
+            .group("group/subgroup")
+            .sort(SortOrder::Ascending)
+            .build()
+            .unwrap();
+        api::ignore(endpoint).query(&client).unwrap();
+    }
+
+    #[test]
+    fn endpoint_search() {
+        let endpoint = ExpectedUrl::builder()
+            .endpoint("groups/group%2Fsubgroup/projects")
+            .add_query_params(&[("search", "name")])
+            .build()
+            .unwrap();
+        let client = SingleTestClient::new_raw(endpoint, "");
+
+        let endpoint = GroupProjects::builder()
+            .group("group/subgroup")
+            .search("name")
+            .build()
+            .unwrap();
+        api::ignore(endpoint).query(&client).unwrap();
+    }
+
+    #[test]
+    fn endpoint_simple() {
+        let endpoint = ExpectedUrl::builder()
+            .endpoint("groups/group%2Fsubgroup/projects")
+            .add_query_params(&[("simple", "true")])
+            .build()
+            .unwrap();
+        let client = SingleTestClient::new_raw(endpoint, "");
+
+        let endpoint = GroupProjects::builder()
+            .group("group/subgroup")
+            .simple(true)
+            .build()
+            .unwrap();
+        api::ignore(endpoint).query(&client).unwrap();
+    }
+
+    #[test]
+    fn endpoint_owned() {
+        let endpoint = ExpectedUrl::builder()
+            .endpoint("groups/group%2Fsubgroup/projects")
+            .add_query_params(&[("owned", "true")])
+            .build()
+            .unwrap();
+        let client = SingleTestClient::new_raw(endpoint, "");
+
+        let endpoint = GroupProjects::builder()
+            .group("group/subgroup")
+            .owned(true)
+            .build()
+            .unwrap();
+        api::ignore(endpoint).query(&client).unwrap();
+    }
+
+    #[test]
+    fn endpoint_starred() {
+        let endpoint = ExpectedUrl::builder()
+            .endpoint("groups/group%2Fsubgroup/projects")
+            .add_query_params(&[("starred", "true")])
+            .build()
+            .unwrap();
+        let client = SingleTestClient::new_raw(endpoint, "");
+
+        let endpoint = GroupProjects::builder()
+            .group("group/subgroup")
+            .starred(true)
+            .build()
+            .unwrap();
+        api::ignore(endpoint).query(&client).unwrap();
+    }
+
+    #[test]
+    fn endpoint_with_issues_enabled() {
+        let endpoint = ExpectedUrl::builder()
+            .endpoint("groups/group%2Fsubgroup/projects")
+            .add_query_params(&[("with_issues_enabled", "true")])
+            .build()
+            .unwrap();
+        let client = SingleTestClient::new_raw(endpoint, "");
+
+        let endpoint = GroupProjects::builder()
+            .group("group/subgroup")
+            .with_issues_enabled(true)
+            .build()
+            .unwrap();
+        api::ignore(endpoint).query(&client).unwrap();
+    }
+
+    #[test]
+    fn endpoint_with_merge_requests_enabled() {
+        let endpoint = ExpectedUrl::builder()
+            .endpoint("groups/group%2Fsubgroup/projects")
+            .add_query_params(&[("with_merge_requests_enabled", "true")])
+            .build()
+            .unwrap();
+        let client = SingleTestClient::new_raw(endpoint, "");
+
+        let endpoint = GroupProjects::builder()
+            .group("group/subgroup")
+            .with_merge_requests_enabled(true)
+            .build()
+            .unwrap();
+        api::ignore(endpoint).query(&client).unwrap();
+    }
+
+    #[test]
+    fn endpoint_with_shared() {
+        let endpoint = ExpectedUrl::builder()
+            .endpoint("groups/group%2Fsubgroup/projects")
+            .add_query_params(&[("with_shared", "true")])
+            .build()
+            .unwrap();
+        let client = SingleTestClient::new_raw(endpoint, "");
+
+        let endpoint = GroupProjects::builder()
+            .group("group/subgroup")
+            .with_shared(true)
+            .build()
+            .unwrap();
+        api::ignore(endpoint).query(&client).unwrap();
+    }
+
+    #[test]
+    fn endpoint_include_subgroups() {
+        let endpoint = ExpectedUrl::builder()
+            .endpoint("groups/group%2Fsubgroup/projects")
+            .add_query_params(&[("include_subgroups", "true")])
+            .build()
+            .unwrap();
+        let client = SingleTestClient::new_raw(endpoint, "");
+
+        let endpoint = GroupProjects::builder()
+            .group("group/subgroup")
+            .include_subgroups(true)
+            .build()
+            .unwrap();
+        api::ignore(endpoint).query(&client).unwrap();
+    }
+
+    #[test]
+    fn endpoint_min_access_level() {
+        let endpoint = ExpectedUrl::builder()
+            .endpoint("groups/group%2Fsubgroup/projects")
+            .add_query_params(&[("min_access_level", "30")])
+            .build()
+            .unwrap();
+        let client = SingleTestClient::new_raw(endpoint, "");
+
+        let endpoint = GroupProjects::builder()
+            .group("group/subgroup")
+            .min_access_level(AccessLevel::Developer)
+            .build()
+            .unwrap();
+        api::ignore(endpoint).query(&client).unwrap();
+    }
+
+    #[test]
+    fn endpoint_with_custom_attributes() {
+        let endpoint = ExpectedUrl::builder()
+            .endpoint("groups/group%2Fsubgroup/projects")
+            .add_query_params(&[("with_custom_attributes", "true")])
+            .build()
+            .unwrap();
+        let client = SingleTestClient::new_raw(endpoint, "");
+
+        let endpoint = GroupProjects::builder()
+            .group("group/subgroup")
+            .with_custom_attributes(true)
+            .build()
+            .unwrap();
+        api::ignore(endpoint).query(&client).unwrap();
+    }
+
+    #[test]
+    fn endpoint_with_security_reports() {
+        let endpoint = ExpectedUrl::builder()
+            .endpoint("groups/group%2Fsubgroup/projects")
+            .add_query_params(&[("with_security_reports", "true")])
+            .build()
+            .unwrap();
+        let client = SingleTestClient::new_raw(endpoint, "");
+
+        let endpoint = GroupProjects::builder()
+            .group("group/subgroup")
+            .with_security_reports(true)
+            .build()
+            .unwrap();
+        api::ignore(endpoint).query(&client).unwrap();
+    }
+}

src/api/groups/subgroups.rs

+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+//! Group subgroups API endpoints.
+//!
+//! These endpoints are used for querying group subgroups.
+
+mod subgroups;
+
+pub use self::subgroups::GroupSubgroups;
+pub use self::subgroups::GroupSubgroupsBuilder;
+pub use self::subgroups::GroupSubgroupsOrderBy;

src/api/groups/subgroups/subgroups.rs

+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+use std::collections::HashSet;
+
+use derive_builder::Builder;
+
+use crate::api::common::{AccessLevel, NameOrId, SortOrder};
+use crate::api::endpoint_prelude::*;
+use crate::api::ParamValue;
+
+/// Keys subgroup results may be ordered by.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum GroupSubgroupsOrderBy {
+    /// Order by the user ID.
+    Id,
+    /// Order by the user display name.
+    Name,
+    /// Order by the path.
+    Path,
+}
+
+impl Default for GroupSubgroupsOrderBy {
+    fn default() -> Self {
+        GroupSubgroupsOrderBy::Name
+    }
+}
+
+impl GroupSubgroupsOrderBy {
+    /// The ordering as a query parameter.
+    fn as_str(self) -> &'static str {
+        match self {
+            GroupSubgroupsOrderBy::Id => "id",