Road to GraphQL

Going forward, we will start on moving to
GraphQL and deprecate the use of
controller-specific endpoints. GraphQL has a number of benefits:

We avoid having to maintain two different APIs.

Callers of the API can request only what they need.

It is versioned by default.

It will co-exist with the current v4 REST API. If we have a v5 API, this should
be a compatibility layer on top of GraphQL.

Although there were some patenting and licensing concerns with GraphQL, these
have been resolved to our satisfaction by the relicensing of the reference
implementations under MIT, and the use of the OWF license for the GraphQL
specification.

Compatibility Guidelines

The HTTP API is versioned using a single number, the current one being 4. This
number symbolises the same as the major version number as described by
SemVer. This mean that backward incompatible changes
will require this version number to change. However, the minor version is
not explicit. This allows for a stable API endpoint, but also means new
features can be added to the API in the same version number.

New features and bug fixes are released in tandem with a new GitLab, and apart
from incidental patch and security releases, are released on the 22nd each
month. Backward incompatible changes (e.g. endpoints removal, parameters
removal etc.), as well as removal of entire API versions are done in tandem
with a major point release of GitLab itself. All deprecations and changes
between two versions should be listed in the documentation. For the changes
between v3 and v4; please read the v3 to v4 documentation

Current status

Currently only API version v4 is available. Version v3 was removed in
GitLab 11.0.

Basic usage

API requests should be prefixed with api and the API version. The API version
is defined in lib/api.rb. For example, the root of the v4 API
is at /api/v4.

Example of a valid API request using cURL:

curl "https://gitlab.example.com/api/v4/projects"

The API uses JSON to serialize data. You don't need to specify .json at the
end of an API URL.

Authentication

Most API requests require authentication, or will only return public data when
authentication is not provided. For
those cases where it is not required, this will be mentioned in the documentation
for each individual endpoint. For example, the /projects/:id endpoint.

Session cookie

When signing in to the main GitLab application, a _gitlab_session cookie is
set. The API will use this cookie for authentication if it is present, but using
the API to generate a new session cookie is currently not supported.

The primary user of this authentication method is the web frontend of GitLab itself,
which can use the API as the authenticated user to get a list of their projects,
for example, without needing to explicitly pass an access token.

Impersonation tokens

Impersonation tokens are a type of personal access token
that can only be created by an admin for a specific user. They are a great fit
if you want to build applications or scripts that authenticate with the API as a specific user.

They are an alternative to directly using the user's password or one of their
personal access tokens, and to using the Sudo feature, since the user's (or admin's, in the case of Sudo)
password/token may not be known or may change over time.

Unknown route

Encoding + in ISO 8601 dates

If you need to include a + in a query parameter, you may need to use %2B instead due
a W3 recommendation that
causes a + to be interpreted as a space. For example, in an ISO 8601 date, you may want to pass
a time in Mountain Standard Time, such as:

2017-10-17T23:11:13.000+05:30

The correct encoding for the query parameter would be:

2017-10-17T23:11:13.000%2B05:30

Clients

There are many unofficial GitLab API Clients for most of the popular
programming languages. Visit the GitLab website for a complete list.