Module gitlab::api

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

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();

Modules

common	API types common to many endpoints.
endpoint_prelude	Endpoint prelude
groups	Group-related API endpoints
projects	Project-related API endpoints
users	User-related API endpoints

Structs

FormParams	A structure for form parameters.
Ignore	A query modifier that ignores the data returned from an endpoint.
Paged	A query modifier that paginates an endpoint.
QueryParams	A structure for query parameters.
Raw	A query modifier that returns the raw data from the endpoint.
Sudo	Query information about the API calling user.
SudoContext	A sudo modifier that can be applied to any endpoint.

Enums

ApiError	Errors which may occur when using API endpoints.
BodyError	Errors which may occur when creating form data.
LinkHeaderParseError	An error which can occur when parsing a link header.
Pagination	Pagination options for GitLab.
PaginationError	Errors which may occur with pagination.

Traits

Client	A trait representing a client which can communicate with a GitLab instance.
Endpoint	A trait for providing the necessary information for a single REST API endpoint.
Pageable	A trait to indicate that an endpoint is pageable.
ParamValue	A trait representing a parameter value.
Query	A trait which represents a query which may be made to a GitLab client.

Functions

ignore	Ignore the resulting data from an endpoint.
paged	Collect data from a paged endpoint.
raw	Return the raw data from the endpoint.
sudo	Create a sudo-elevated version of an endpoint.