Socket
Socket
Sign inDemoInstall

@gitbeaker/rest

Package Overview
Dependencies
20
Maintainers
1
Versions
91
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

    @gitbeaker/rest

Cross Platform implementation of the GitLab API


Version published
Weekly downloads
255K
decreased by-1.73%
Maintainers
1
Install size
2.40 MB
Created
Weekly downloads
 

Package description

What is @gitbeaker/rest?

@gitbeaker/rest is an npm package that provides a comprehensive and easy-to-use interface for interacting with the GitLab REST API. It allows developers to perform a wide range of actions on GitLab, such as managing projects, issues, users, and more.

What are @gitbeaker/rest's main functionalities?

Project Management

This feature allows you to manage projects on GitLab. The code sample demonstrates how to create a new project using the GitLab REST API.

const { Gitlab } = require('@gitbeaker/rest');
const api = new Gitlab({ token: 'your_access_token' });

async function createProject() {
  const project = await api.Projects.create({ name: 'new-project' });
  console.log(project);
}

createProject();

Issue Management

This feature allows you to manage issues on GitLab. The code sample demonstrates how to create a new issue in a project using the GitLab REST API.

const { Gitlab } = require('@gitbeaker/rest');
const api = new Gitlab({ token: 'your_access_token' });

async function createIssue() {
  const issue = await api.Issues.create(1, { title: 'New Issue', description: 'Issue description' });
  console.log(issue);
}

createIssue();

User Management

This feature allows you to manage users on GitLab. The code sample demonstrates how to list all users using the GitLab REST API.

const { Gitlab } = require('@gitbeaker/rest');
const api = new Gitlab({ token: 'your_access_token' });

async function listUsers() {
  const users = await api.Users.all();
  console.log(users);
}

listUsers();

Repository Management

This feature allows you to manage repositories on GitLab. The code sample demonstrates how to list all files in a repository using the GitLab REST API.

const { Gitlab } = require('@gitbeaker/rest');
const api = new Gitlab({ token: 'your_access_token' });

async function listRepositoryFiles() {
  const files = await api.Repositories.tree(1);
  console.log(files);
}

listRepositoryFiles();

Other packages similar to @gitbeaker/rest

Readme

Source


gitbeaker


My open source work is supported by the community


Special thanks to:



pipeline status coverage report Code Climate maintainability Auto All Contributors Prettier Licence: MIT Install Size: Rest

A Typed GitLab SDK for Browsers, Node.js, and Deno.

Table of Contents

Features

  • Complete - All features of Gitlab's exposed APIs are covered up to version 16.5. See here for the full list.
  • Universal - Works in all modern browsers, Node.js, and Deno.
  • Tested - All libraries have > 80% test coverage.
  • Typed - All libraries have extensive TypeScript declarations.

Usage

Browsers Load @gitbeaker/rest directly from esm.sh
<script type="module">
  import { Gitlab } from 'https://esm.sh/@gitbeaker/rest';
</script>
Deno Load @gitbeaker/rest directly from esm.sh
import { Gitlab } from 'https://esm.sh/@gitbeaker/rest?dts';
Node 18+

Install with npm install @gitbeaker/rest, or yarn add @gitbeaker/rest

import { Gitlab } from '@gitbeaker/rest';

API Client

Instantiate the library using a basic token created in your Gitlab Profile

const api = new Gitlab({
  token: 'personaltoken',
});

Available instantiating options:

NameOptionalDefaultDescription
hostYeshttps://gitlab.comGitlab Instance Host URL
tokenNo*N/APersonal Token. Required (one of the three tokens are required)
oauthTokenNo*N/AOAuth Token. Required (one of the three tokens are required)
jobTokenNo*N/ACI Job Token. Required (one of the three tokens are required)
rejectUnauthorizedYestrueHttp Certificate setting, Only applies to non-browser releases and HTTPS hosts urls
sudoYesfalseSudo query parameter
camelizeYesfalseCamelizes all response body keys
requesterFnNo@gitbeaker/rest & @gitbeaker/cli : fetch-based, The @gitbeaker/core package does not have a default and thus must be set explicitlyRequest Library Wrapper
queryTimeoutYes300000Query Timeout in ms
profileTokenYesN/ARequests Profiles Token
profileModeYesexecutionRequests Profiles Token
rateLimitsNoDEFAULT_RATE_LIMITSGlobal and endpoint specific adjustable rate limits

*One of these options must be supplied.

Expanded Payloads

For simplicity, only the response body is returned from the API methods. However, seeing additional response fields, such as the status, headers, etc., may be helpful. For this purpose, an additional optional parameter, showExpanded can be passed for most API methods.

For methods that return non-paginated results, the payload has this structure:

type ResponseBodyTypes =
  | Record<string, unknown>
  | Record<string, unknown>[]
  | ReadableStream
  | Blob
  | string
  | string[]
  | number
  | void
  | null;

interface FormattedResponse<T extends ResponseBodyTypes = ResponseBodyTypes> {
  body: T;
  headers: Record<string, string>;
  status: number;
}

For methods that return paginated results, the payload also includes paginated information outlined in the Pagination documentation

Pagination

Available pagination options:

NameKeysetOffsetTypeDefaultDescription
paginationXX'offset' or 'keyset''offset'Defines which pagination type should be used
perPageXXNumber20Amount of results per request
orderByXStringWhat field the results should be ordered by
sortX'asc' or 'desc''asc'The direction of sort for the results
maxPagesXNumberN/AMaximum amount of requests that should be made
pageXNumberN/ASpecific page to be retrieved
showExpandedXBooleanfalseReturns with the pagination information in addition to the data
Offset Pagination

For any .all() function on a resource, it will return all the items from Gitlab. This can be troublesome if there are many items, as the request itself can take a while to be fulfilled. As such, a maxPages option can be passed to limit the scope of the all function.

import { Gitlab } from '@gitbeaker/rest';

const api = new Gitlab({
  host: 'http://example.com',
  token: 'personaltoken',
});

let projects = await api.Projects.all({ maxPages: 2 });

You can also use this in conjunction with the perPage argument which would override the default of 30 per page set by Gitlab:

import { Gitlab } from '@gitbeaker/rest';

const api = new Gitlab({
  host: 'http://example.com',
  token: 'personaltoken',
});

let projects = await api.Projects.all({ maxPages: 2, perPage: 40 });

Additionally, if you would like to get back the pagination information, to know how many total pages there are for example, pass the option showExpanded. If there are multiple results the pagination property will be included as shown below:

...
const { data, paginationInfo } = await api.Projects.all({
  perPage:40,
  maxPages:2,
  showExpanded: true
});
...

This will result in a response in this format:

data: [
...
],
paginationInfo: {
  next: 4,
  current: 2,
  previous: 1,
  perPage: 3,
}

Note: Supplying any pagination restrictions is call intensive. Some resources will require many requests which can put a significant load on the Gitlab Server. The general best practice would be setting the page request option to only return the first page if all results are not required.

Keyset Pagination

Similarly, support for Keyset pagination can be toggled on by passing a pagination parameter as a query option

const { data } = await api.Projects.all({
  pagination: 'keyset',
  sort: 'asc',
  orderBy: 'created_at',
});

Rate Limits

Rate limits are completely customizable, and are used to limit the request rate between consecutive API requests within the library. By default, all non-specified endpoints use a 3000 rps rate limit, while some endpoints have much smaller rates as dictated by the Gitlab Docs. See below for the default values:

const DEFAULT_RATE_LIMITS = Object.freeze({
  // Default rate limit
  '**': 3000,

  // Import/Export
  'projects/import': 6,
  'projects/*/export': 6,
  'projects/*/download': 1,
  'groups/import': 6,
  'groups/*/export': 6,
  'groups/*/download': 1,

  // Note creation
  'projects/*/issues/*/notes': {
    method: 'post',
    limit: 300,
  },
  'projects/*/snippets/*/notes': {
    method: 'post',
    limit: 300,
  },
  'projects/*/merge_requests/*/notes': {
    method: 'post',
    limit: 300,
  },
  'groups/*/epics/*/notes': {
    method: 'post',
    limit: 300,
  },

  // Repositories - get file archive
  'projects/*/repository/archive*': 5,

  // Project Jobs
  'projects/*/jobs': 600,

  // Member deletion
  'projects/*/members': 60,
  'groups/*/members': 60,
});

Rate limits can be overridden when instantiating a API wrapper. For ease of use, these limits are configured using glob patterns, and can be formatted in two ways.

  1. The glob for the endpoint with the corresponding rate per second
  2. The glob for the endpoint, with an object specifying the specific method for the endpoint and the corresponding rate limit
const api = new Gitlab({
  token: 'token',
  rateLimits: {
    '**': 30,
    'projects/import/*': 40,
    'projects/*/issues/*/notes': {
      method: 'post',
      limit: 300,
    },
  },
});

Error Handling

Request errors are returned back within a plain Error instance, using the cause to hold the original response and a text description of the error pulled from the response's error or message fields if JSON, or its plain text value:

class GitbeakerError extends Error {
  constructor(
    message: string,
    options?: {
      cause: {
        description: string;
        request: Request;
        response: Response;
      };
    },
  ) {
    super(message, options);
    this.name = 'GitbeakerError';
  }
}

Note, the message is assigned to the Response's statusText, and the Request and Response types are from the NodeJS API.

Examples

Once you have your library instantiated, you can utilize many of the API's functionality:

Using the await/async method

import { Gitlab } from '@gitbeaker/rest';

const api = new Gitlab({
  host: 'http://example.com',
  token: 'personaltoken',
});

// Listing users
let users = await api.Users.all();

// Or using Promise-Then notation
api.Projects.all().then((projects) => {
  console.log(projects);
});

A general rule about all the function parameters:

  • If it's a required parameter, it is a named argument in the functions
  • If it's an optional parameter, it is defined in a options object following the named arguments

ie.

import { Projects } from '@gitbeaker/rest';

const projectsAPI = new Projects({
  host: 'http://example.com',
  token: 'personaltoken',
});

projectsAPI.create({
  //options defined in the Gitlab API documentation
});

Contributors

Justin Dalrymple Dylan DesRosier Mike Wyatt Cory Zibeill Martin Bour akira345 Pavel Birukov Joseph Petersen Louis Cherel Adam Dehnel Ev Haus Loïc Mahieu Giuseppe Angri jennparise Oscar Daniel Ruf schindld Alvaro Daniel Moore Dylan M. Taylor Corentin Mors xatavian Yevgeny Petukhov Mickaël Tricot Andrea Flavien Bridault s-kazuki Kipras Melnikovas xieyu st1gok Max Wittig Niklas Lochschmidt Ilya Dus Omar Awamry Hennadii Varava xiezht Martin Helmich Sean McGivern Clemens Lieb Vojtěch Sajdl divido Vincent Boulaye Aliyss Snow Mahmoud Saada Feng Yu Roy Jacobs Paul Lemke Ian Jenkins nilennoct Laffargue Michael Martin Howarth Christoph Lehmann Frank V Salim Benabbou Tamás Török-Vistai Martin Benninger fewieden Jeff Pelton Claude Abounegm Stefan Hall Jordan Wallet zhao0 Joshua Grosso Isaac Ouellet Therrien Rajat Sharma Cesar B. Igor Katsuba Michael Townsend bodtx Artem Munif Tanjim Quentin Dreyer Norm MacLennan jnovick Fabian Aussems Michael Matzka CraigAllardyce Bruno Guimarães Lukas Eipert Maximilian Krauß Evolution Engineering WEBER Logan Anton Zhukov Nicholas Loomans Carl Kittelberger Patrik Votoček Kyrylo Fedorov Claudio Vellage Seb0uil Rafael Mello Théis Bazin Spencer Salisbury Simone Corsi Bambii Will ArnaudTA Benjamin Beret Alessandro Diez artlist-scottambrose Martin Dreher Elan Ruusamäe artemoire Pieter Willekens David Claybourne Dom Harrington Kohei Seino JounQin Elaine Mattos DK Koen Brouwer

This started as a fork from node-gitlab-legacy but I ended up rewriting much of the code. Here are the original work's contributors.

Keywords

FAQs

Last updated on 12 Apr 2024

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc