1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107

// 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.

#![warn(missing_docs)]

//! API endpoint structures
//!
//! The types in this module are meant to aid in constructing the appropriate calls using type-safe
//! Rust idioms.
//!
//! All endpoints use the builder pattern and have their members as private so that there are no
//! API implications of adding new members for additional query parameters in future GitLab
//! releases.
//!
//! # Example
//!
//! ```rust,no_run
//! use serde::Deserialize;
//! use gitlab::Gitlab;
//! use gitlab::api::{self, projects, Query};
//!
//! // The return type of a `Project`. Note that GitLab may contain more information, but you can
//! // define your structure to only fetch what is needed.
//! #[derive(Debug, Deserialize)]
//! struct Project {
//!     name: String,
//! }
//!
//! // Create the client.
//! let client = Gitlab::new("gitlab.com", "private-token").unwrap();
//!
//! // Create a simple endpoint. This one gets the "gitlab-org/gitlab" project information.
//! let endpoint = projects::Project::builder().project("gitlab-org/gitlab").build().unwrap();
//! // Call the endpoint. The return type decides how to represent the value.
//! let project: Project = endpoint.query(&client).unwrap();
//! // For some endpoints (mainly `POST` endpoints), you may want to ignore the result.
//! // `api::ignore` can be used to do this.
//! let _: () = api::ignore(endpoint).query(&client).unwrap();
//!
//! // Some endpoints support pagination. They work on their own or via the `api::paged` function
//! // to get further results.
//! let pageable_endpoint = projects::Projects::builder().build().unwrap();
//! // The endpoint on its own is just the first page of results (usually 20 entries).
//! let first_page: Vec<Project> = pageable_endpoint.query(&client).unwrap();
//! // `api::paged` can be used to get results up to some count or all results.
//! let first_200_projects: Vec<Project> = api::paged(pageable_endpoint, api::Pagination::Limit(200)).query(&client).unwrap();
//!
//! // Builders accept strings or integers for some fields. This is done wherever GitLab supports
//! // either IDs or names being used.
//! let endpoint = projects::Project::builder().project(278964).build().unwrap();
//! // The `api::raw` function can be used to return the raw data from the endpoint. This is
//! // usually meant for endpoints which represent file contents, pipeline artifacts, etc., but may
//! // be used with any endpoint.
//! let raw_data: Vec<u8> = api::raw(endpoint).query(&client).unwrap();
//! ```

mod client;
mod endpoint;
mod error;
mod ignore;
mod paged;
mod params;
pub(crate) mod query;
mod raw;
mod sudo;

pub mod endpoint_prelude;

pub mod common;
pub mod groups;
pub mod projects;
pub mod users;

pub(crate) mod helpers;

pub use self::client::Client;

pub use self::endpoint::Endpoint;

pub use self::error::ApiError;
pub use self::error::BodyError;

pub use self::ignore::ignore;
pub use self::ignore::Ignore;

pub use self::paged::paged;
pub use self::paged::LinkHeaderParseError;
pub use self::paged::Pageable;
pub use self::paged::Paged;
pub use self::paged::Pagination;
pub use self::paged::PaginationError;

pub use self::params::FormParams;
pub use self::params::ParamValue;
pub use self::params::QueryParams;

pub use self::query::Query;

pub use self::raw::raw;
pub use self::raw::Raw;

pub use self::sudo::sudo;
pub use self::sudo::Sudo;
pub use self::sudo::SudoContext;