Module api

Expand description

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.
deploy_keys: Global deploy key related API endpoints
endpoint_prelude: Endpoint prelude
groups: Group-related API endpoints
issues: Issue API endpoints and types.
job: Global deploy key related API endpoints
merge_requests: Merge request-related API endpoints
packages: Packages API types.
personal_access_tokens: Personal access token-related API endpoints
projects: Project-related API endpoints
retry: Retry client wrapper
runners: Runner-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.
JsonParams: A structure for JSON parameters.
LazilyPagedIter: An iterator which yields items from a paginated result.
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.
UrlBase: URL bases for endpoints.

Traits§

AsyncClient: A trait representing an asynchronous client which can communicate with a GitLab instance.
AsyncQuery: A trait which represents an asynchronous query which may be made to a GitLab client.
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.
RestClient: A trait representing a client which can communicate with a GitLab instance via REST.

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.