gitlab/
api.rs

1// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
2// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
3// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
4// option. This file may not be copied, modified, or distributed
5// except according to those terms.
6
7#![warn(missing_docs)]
8
9//! API endpoint structures
10//!
11//! The types in this module are meant to aid in constructing the appropriate calls using type-safe
12//! Rust idioms.
13//!
14//! All endpoints use the builder pattern and have their members as private so that there are no
15//! API implications of adding new members for additional query parameters in future GitLab
16//! releases.
17//!
18//! # Example
19//!
20//! ```rust,no_run
21//! use serde::Deserialize;
22//! use gitlab::Gitlab;
23//! use gitlab::api::{self, projects, Query};
24//!
25//! // The return type of a `Project`. Note that GitLab may contain more information, but you can
26//! // define your structure to only fetch what is needed.
27//! #[derive(Debug, Deserialize)]
28//! struct Project {
29//!     name: String,
30//! }
31//!
32//! // Create the client.
33//! let client = Gitlab::new("gitlab.com", "private-token").unwrap();
34//!
35//! // Create a simple endpoint. This one gets the "gitlab-org/gitlab" project information.
36//! let endpoint = projects::Project::builder().project("gitlab-org/gitlab").build().unwrap();
37//! // Call the endpoint. The return type decides how to represent the value.
38//! let project: Project = endpoint.query(&client).unwrap();
39//! // For some endpoints (mainly `POST` endpoints), you may want to ignore the result.
40//! // `api::ignore` can be used to do this.
41//! let _: () = api::ignore(endpoint).query(&client).unwrap();
42//!
43//! // Some endpoints support pagination. They work on their own or via the `api::paged` function
44//! // to get further results.
45//! let pageable_endpoint = projects::Projects::builder().build().unwrap();
46//! // The endpoint on its own is just the first page of results (usually 20 entries).
47//! let first_page: Vec<Project> = pageable_endpoint.query(&client).unwrap();
48//! // `api::paged` can be used to get results up to some count or all results.
49//! let first_200_projects: Vec<Project> = api::paged(pageable_endpoint, api::Pagination::Limit(200)).query(&client).unwrap();
50//!
51//! // Builders accept strings or integers for some fields. This is done wherever GitLab supports
52//! // either IDs or names being used.
53//! let endpoint = projects::Project::builder().project(278964).build().unwrap();
54//! // The `api::raw` function can be used to return the raw data from the endpoint. This is
55//! // usually meant for endpoints which represent file contents, pipeline artifacts, etc., but may
56//! // be used with any endpoint.
57//! let raw_data: Vec<u8> = api::raw(endpoint).query(&client).unwrap();
58//! ```
59
60mod client;
61mod endpoint;
62mod error;
63mod ignore;
64mod paged;
65mod params;
66pub(crate) mod query;
67mod raw;
68mod sudo;
69
70pub mod endpoint_prelude;
71
72pub mod common;
73pub mod deploy_keys;
74pub mod events;
75pub mod groups;
76pub mod issues;
77pub mod job;
78pub mod merge_requests;
79pub mod packages;
80pub mod personal_access_tokens;
81pub mod projects;
82pub mod registry;
83pub mod retry;
84pub mod runners;
85pub mod users;
86
87pub(crate) mod helpers;
88
89pub use self::client::AsyncClient;
90pub use self::client::Client;
91pub use self::client::RestClient;
92
93pub use self::endpoint::Endpoint;
94pub use self::endpoint::UrlBase;
95
96pub use self::error::ApiError;
97pub use self::error::BodyError;
98
99pub use self::ignore::ignore;
100pub use self::ignore::Ignore;
101
102pub use self::paged::paged;
103pub use self::paged::LazilyPagedIter;
104pub use self::paged::LinkHeaderParseError;
105pub use self::paged::Pageable;
106pub use self::paged::Paged;
107pub use self::paged::Pagination;
108pub use self::paged::PaginationError;
109
110pub use self::params::FormParams;
111pub use self::params::JsonParams;
112pub use self::params::ParamValue;
113pub use self::params::QueryParams;
114
115pub use self::query::AsyncQuery;
116pub use self::query::Query;
117
118pub use self::raw::raw;
119pub use self::raw::Raw;
120
121pub use self::sudo::sudo;
122pub use self::sudo::Sudo;
123pub use self::sudo::SudoContext;
gitlab/api.rs

gitlab/
api.rs
