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 groups;
75pub mod issues;
76pub mod job;
77pub mod merge_requests;
78pub mod packages;
79pub mod personal_access_tokens;
80pub mod projects;
81pub mod retry;
82pub mod runners;
83pub mod users;
84
85pub(crate) mod helpers;
86
87pub use self::client::AsyncClient;
88pub use self::client::Client;
89pub use self::client::RestClient;
90
91pub use self::endpoint::Endpoint;
92pub use self::endpoint::UrlBase;
93
94pub use self::error::ApiError;
95pub use self::error::BodyError;
96
97pub use self::ignore::ignore;
98pub use self::ignore::Ignore;
99
100pub use self::paged::paged;
101pub use self::paged::LazilyPagedIter;
102pub use self::paged::LinkHeaderParseError;
103pub use self::paged::Pageable;
104pub use self::paged::Paged;
105pub use self::paged::Pagination;
106pub use self::paged::PaginationError;
107
108pub use self::params::FormParams;
109pub use self::params::JsonParams;
110pub use self::params::ParamValue;
111pub use self::params::QueryParams;
112
113pub use self::query::AsyncQuery;
114pub use self::query::Query;
115
116pub use self::raw::raw;
117pub use self::raw::Raw;
118
119pub use self::sudo::sudo;
120pub use self::sudo::Sudo;
121pub use self::sudo::SudoContext;
gitlab/api.rs

gitlab/
api.rs
