gitbeaker/packages/rest

^{My open source work is supported by the community}

^{Special thanks to:}

Review merge requests in Slack to merge code faster

_{Improve your code review process by creating an ephemeral channel per merge request.}

---

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

Table of Contents

• Features
• Usage
• API Client
  • Pagination
  • Error Handling
• Examples
• Testing
• FAQ
• Contributors
• Changelog

Features

• Complete - All features of Gitlab's exposed APIs are covered up to version 16.0.
• 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:

Name	Optional	Default	Description
host	Yes	https://gitlab.com	Gitlab Instance Host URL
token	No*	N/A	Personal Token. Required (one of the three tokens are required)
oauthToken	No*	N/A	OAuth Token. Required (one of the three tokens are required)
jobToken	No*	N/A	CI Job Token. Required (one of the three tokens are required)
rejectUnauthorized	Yes	true	Http Certificate setting, Only applies to non-browser releases and HTTPS hosts urls
sudo	Yes	false	Sudo query parameter
camelize	Yes	false	Camelizes all response body keys
requesterFn	No	@gitbeaker/rest & @gitbeaker/cli : fetch-based, The @gitbeaker/core package does not have a default and thus must be set explicitly	Request Library Wrapper
queryTimeout	Yes	300000	Query Timeout in ms
profileToken	Yes	N/A	Requests Profiles Token
profileMode	Yes	execution	Requests Profiles Token

*One of these options must be supplied.

Pagination

Available pagination options:

Name	Keyset	Offset	Type	Default	Description
pagination	X	X	'offset' or 'keyset'	'offset'	Defines which pagination type should be used
perPage	X	X	Number	20	Amount of results per request
orderBy	X		String		What field the results should be ordered by
sort	X		'asc' or 'desc'	'asc'	The direction of sort for the results
maxPages		X	Number	N/A	Maximum amount of requests that should be made
page		X	Number	N/A	Specific page to be retrieved
showExpanded		X	Boolean	false	Returns 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',
});

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:

Error: Bad Request
<stack trace>
{
  [cause]: {
    description: <text description>,
    response: <original Response object>
  }
}

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

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.