BigW Consortium Gitlab

README.md 15.8 KB
Newer Older
1
# GitLab API
2

3
Automate GitLab via a simple and powerful API. All definitions can be found
4
under [`/lib/api`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api).
5

6
## Resources
7

8 9 10
Documentation for various API resources can be found separately in the
following locations:

11
- [Award Emoji](award_emoji.md)
12
- [Branches](branches.md)
13
- [Broadcast Messages](broadcast_messages.md)
Shinya Maeda committed
14 15
- [Project-level Variables](project_level_variables.md)
- [Group-level Variables](group_level_variables.md)
16
- [Commits](commits.md)
17
- [Custom Attributes](custom_attributes.md)
18
- [Deployments](deployments.md)
19
- [Deploy Keys](deploy_keys.md)
20
- [Environments](environments.md)
21
- [Events](events.md)
22
- [Feature flags](features.md)
23 24
- [Gitignores templates](templates/gitignores.md)
- [GitLab CI Config templates](templates/gitlab_ci_ymls.md)
25
- [Groups](groups.md)
26 27
- [Group Access Requests](access_requests.md)
- [Group Members](members.md)
28
- [Issues](issues.md)
29
- [Issue Boards](boards.md)
30
- [Jobs](jobs.md)
31
- [Keys](keys.md)
32
- [Labels](labels.md)
33
- [Merge Requests](merge_requests.md)
34 35
- [Project milestones](milestones.md)
- [Group milestones](group_milestones.md)
36
- [Namespaces](namespaces.md)
37
- [Notes](notes.md) (comments)
38
- [Notification settings](notification_settings.md)
39
- [Open source license templates](templates/licenses.md)
40
- [Pages Domains](pages_domains.md)
41
- [Pipelines](pipelines.md)
42
- [Pipeline Triggers](pipeline_triggers.md)
Shinya Maeda committed
43
- [Pipeline Schedules](pipeline_schedules.md)
44
- [Projects](projects.md) including setting Webhooks
45 46
- [Project Access Requests](access_requests.md)
- [Project Members](members.md)
47
- [Project Snippets](project_snippets.md)
48
- [Protected Branches](protected_branches.md)
49 50
- [Repositories](repositories.md)
- [Repository Files](repository_files.md)
51
- [Runners](runners.md)
52 53 54
- [Services](services.md)
- [Session](session.md)
- [Settings](settings.md)
55
- [Sidekiq metrics](sidekiq_metrics.md)
56 57
- [System Hooks](system_hooks.md)
- [Tags](tags.md)
58
- [Todos](todos.md)
59
- [Users](users.md)
60
- [Validate CI configuration](lint.md)
61
- [V3 to V4](v3_to_v4.md)
62
- [Version](version.md)
63
- [Wikis](wikis.md)
64

65 66
## Road to GraphQL

67 68 69 70 71 72 73 74 75 76 77 78 79 80 81
Going forward, we will start on moving to
[GraphQL](http://graphql.org/learn/best-practices/) and deprecate the use of
controller-specific endpoints. GraphQL has a number of benefits:

1. We avoid having to maintain two different APIs.
2. Callers of the API can request only what they need.
3. 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.
82

83 84 85
## Basic usage

API requests should be prefixed with `api` and the API version. The API version
86 87
is defined in [`lib/api.rb`][lib-api-url]. For example, the root of the v4 API
is at `/api/v4`.
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114

For endpoints that require [authentication](#authentication), you need to pass
a `private_token` parameter via query string or header. If passed as a header,
the header name must be `PRIVATE-TOKEN` (uppercase and with a dash instead of
an underscore).

Example of a valid API request:

```
GET /projects?private_token=9koXpg98eAheJpvBs5tK
```

Example of a valid API request using cURL and authentication via header:

```shell
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects"
```

Example of a valid API request using cURL and authentication via a query string:

```shell
curl "https://gitlab.example.com/api/v4/projects?private_token=9koXpg98eAheJpvBs5tK"
```

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

115
## Authentication
116

117 118 119
Most API requests require authentication via a session cookie or token. 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](projects.md).
120

121
There are three types of access tokens available:
122

123 124 125
1. [OAuth2 tokens](#oauth2-tokens)
1. [Private tokens](#private-tokens)
1. [Personal access tokens](#personal-access-tokens)
126

127 128
If authentication information is invalid or omitted, an error message will be
returned with status code `401`:
129 130 131 132 133 134 135

```json
{
  "message": "401 Unauthorized"
}
```

136
### Session cookie
137 138 139 140 141

When signing in to GitLab as an ordinary user, 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.

142
### OAuth2 tokens
143

144 145 146 147
You can use an OAuth 2 token to authenticate with the API by passing it either in the
`access_token` parameter or in the `Authorization` header.

Example of using the OAuth2 token in the header:
148

149
```shell
150
curl --header "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api/v4/projects
151 152
```

153 154
Read more about [GitLab as an OAuth2 client](oauth2.md).

155
### Private tokens
156

157 158 159
Private tokens provide full access to the GitLab API. Anyone with access to
them can interact with GitLab as if they were you. You can find or reset your
private token in your account page (`/profile/account`).
160

161
For examples of usage, [read the basic usage section](#basic-usage).
162

163
### Personal access tokens
164

165 166 167
Instead of using your private token which grants full access to your account,
personal access tokens could be a better fit because of their granular
permissions.
168

169 170 171
Once you have your token, pass it to the API using either the `private_token`
parameter or the `PRIVATE-TOKEN` header. For examples of usage,
[read the basic usage section](#basic-usage).
172

173
[Read more about personal access tokens.][pat]
174

175
### Impersonation tokens
176

177
> [Introduced][ce-9099] in GitLab 9.0. Needs admin permissions.
178

179
Impersonation tokens are a type of [personal access token][pat]
180
that can only be created by an admin for a specific user.
181

182 183 184 185 186
They are a better alternative to using the user's password/private token
or using the [Sudo](#sudo) feature which also requires the admin's password
or private token, since the password/token can change over time. Impersonation
tokens are a great fit if you want to build applications or tools which
authenticate with the API as a specific user.
187

188
For more information, refer to the
189
[users API](users.md#retrieve-user-impersonation-tokens) docs.
190

191 192
For examples of usage, [read the basic usage section](#basic-usage).

193
### Sudo
194

195
> Needs admin permissions.
196

197
All API requests support performing an API call as if you were another user,
198
provided your private token is from an administrator account. You need to pass
199 200 201
the `sudo` parameter either via query string or a header with an ID/username of
the user you want to perform the operation as. If passed as a header, the
header name must be `SUDO` (uppercase).
202

203 204
If a non administrative `private_token` is provided, then an error message will
be returned with status code `403`:
205 206 207

```json
{
208
  "message": "403 Forbidden - Must be admin to use sudo"
209 210 211
}
```

212
If the sudo user ID or username cannot be found, an error message will be
213
returned with status code `404`:
214 215 216 217 218 219 220

```json
{
  "message": "404 Not Found: No user id or username for: <id/username>"
}
```

221 222 223 224
---

Example of a valid API call and a request using cURL with sudo request,
providing a username:
225

226
```
227
GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=username
228
```
229

230
```shell
231
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: username" "https://gitlab.example.com/api/v4/projects"
232 233
```

234 235
Example of a valid API call and a request using cURL with sudo request,
providing an ID:
236

237
```
238
GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23
239
```
240

241
```shell
242
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: 23" "https://gitlab.example.com/api/v4/projects"
243
```
244

245 246 247 248 249 250 251 252 253 254 255 256
## Status codes

The API is designed to return different status codes according to context and
action. This way, if a request results in an error, the caller is able to get
insight into what went wrong.

The following table gives an overview of how the API functions generally behave.

| Request type | Description |
| ------------ | ----------- |
| `GET`   | Access one or more resources and return the result as JSON. |
| `POST`  | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. |
257 258
| `GET` / `PUT` | Return `200 OK` if the resource is accessed or modified successfully. The (modified) result is returned as JSON. |
| `DELETE` | Returns `204 No Content` if the resuource was deleted successfully. |
259 260 261 262 263 264 265 266 267 268 269 270 271 272 273

The following table shows the possible return codes for API requests.

| Return values | Description |
| ------------- | ----------- |
| `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON. |
| `204 No Content` | The server has successfully fulfilled the request and that there is no additional content to send in the response payload body. |
| `201 Created` | The `POST` request was successful and the resource is returned as JSON. |
| `304 Not Modified` | Indicates that the resource has not been modified since the last request. |
| `400 Bad Request` | A required attribute of the API request is missing, e.g., the title of an issue is not given. |
| `401 Unauthorized` | The user is not authenticated, a valid [user token](#authentication) is necessary. |
| `403 Forbidden` | The request is not allowed, e.g., the user is not allowed to delete a project. |
| `404 Not Found` | A resource could not be accessed, e.g., an ID for a resource could not be found. |
| `405 Method Not Allowed` | The request is not supported. |
| `409 Conflict` | A conflicting resource already exists, e.g., creating a project with a name that already exists. |
274
| `412` | Indicates the request was denied. May happen if the `If-Unmodified-Since` header is provided when trying to delete a resource, which was modified in between. |
275 276
| `422 Unprocessable` | The entity could not be processed. |
| `500 Server Error` | While handling the request something went wrong server-side. |
277

Dmitriy Zaporozhets committed
278
## Pagination
Nihad Abbasov committed
279

280 281
Sometimes the returned result will span across many pages. When listing
resources you can pass the following parameters:
Nihad Abbasov committed
282

283 284
| Parameter | Description |
| --------- | ----------- |
285 286
| `page`    | Page number (default: `1`) |
| `per_page`| Number of items to list per page (default: `20`, max: `100`) |
Nihad Abbasov committed
287

288 289 290
In the example below, we list 50 [namespaces](namespaces.md) per page.

```bash
291
curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/namespaces?per_page=50
292 293
```

294
### Pagination Link header
295

296
[Link headers](http://www.w3.org/wiki/LinkHeader) are sent back with each
297 298
response. They have `rel` set to prev/next/first/last and contain the relevant
URL. Please use these links instead of generating your own URLs.
299

300 301 302 303 304
In the cURL example below, we limit the output to 3 items per page (`per_page=3`)
and we request the second page (`page=2`) of [comments](notes.md) of the issue
with ID `8` which belongs to the project with ID `8`:

```bash
305
curl --head --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/8/issues/8/notes?per_page=3&page=2
306 307
```

308 309 310 311 312 313 314 315
The response will then be:

```
HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Length: 1103
Content-Type: application/json
Date: Mon, 18 Jan 2016 09:43:18 GMT
316
Link: <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="prev", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="next", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="first", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="last"
317 318 319 320 321 322 323 324 325 326
Status: 200 OK
Vary: Origin
X-Next-Page: 3
X-Page: 2
X-Per-Page: 3
X-Prev-Page: 1
X-Request-Id: 732ad4ee-9870-4866-a199-a9db0cde3c86
X-Runtime: 0.108688
X-Total: 8
X-Total-Pages: 3
327 328 329 330
```

### Other pagination headers

331 332 333 334 335 336 337 338 339 340
Additional pagination headers are also sent back.

| Header | Description |
| ------ | ----------- |
| `X-Total`       | The total number of items |
| `X-Total-Pages` | The total number of pages |
| `X-Per-Page`    | The number of items per page |
| `X-Page`        | The index of the current page (starting at 1) |
| `X-Next-Page`   | The index of the next page |
| `X-Prev-Page`   | The index of the previous page |
341

342 343
## Namespaced path encoding

344
If using namespaced API calls, make sure that the `NAMESPACE/PROJECT_NAME` is
345 346
URL-encoded.

347
For example, `/` is represented by `%2F`:
348 349

```
350 351 352 353 354 355 356 357 358 359 360 361
GET /api/v4/projects/diaspora%2Fdiaspora
```

## Branches & tags name encoding

If your branch or tag contains a `/`, make sure the branch/tag name is
URL-encoded.

For example, `/` is represented by `%2F`:

```
GET /api/v4/projects/1/branches/my%2Fbranch/commits
362 363
```

364
## `id` vs `iid`
Dmitriy Zaporozhets committed
365

366 367 368 369
When you work with the API, you may notice two similar fields in API entities:
`id` and `iid`. The main difference between them is scope.

For example, an issue might have `id: 46` and `iid: 5`.
370

371 372
| Parameter | Description |
| --------- | ----------- |
373 374
| `id`  | Is unique across all issues and is used for any API call |
| `iid` | Is unique only in scope of a single project. When you browse issues or merge requests with the Web UI, you see the `iid` |
Dmitriy Zaporozhets committed
375

376
That means that if you want to get an issue via the API you should use the `id`:
377

378
```
379
GET /projects/42/issues/:id
380
```
Dmitriy Zaporozhets committed
381

382 383
On the other hand, if you want to create a link to a web page you should use
the `iid`:
Dmitriy Zaporozhets committed
384

385
```
386
GET /projects/42/issues/:iid
387
```
388 389 390

## Data validation and error reporting

391
When working with the API you may encounter validation errors, in which case
392 393
the API will answer with an HTTP `400` status.

394 395
Such errors appear in two cases:

396
- A required attribute of the API request is missing, e.g., the title of an
397
  issue is not given
398
- An attribute did not pass the validation, e.g., user bio is too long
399 400 401

When an attribute is missing, you will get something like:

402
```
403 404 405 406 407 408
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "message":"400 (Bad request) \"title\" not given"
}
```
409

410 411
When a validation error occurs, error messages will be different. They will
hold all details of validation errors:
412

413
```
414 415 416 417 418 419 420
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "message": {
        "bio": [
            "is too long (maximum is 255 characters)"
        ]
421
    }
422 423
}
```
424

425 426
This makes error messages more machine-readable. The format can be described as
follows:
427

428 429 430 431 432 433 434 435 436
```json
{
    "message": {
        "<property-name>": [
            "<error-message>",
            "<error-message>",
            ...
        ],
        "<embed-entity>": {
437 438 439 440 441 442 443
            "<property-name>": [
                "<error-message>",
                "<error-message>",
                ...
            ],
        }
    }
444 445 446
}
```

447
## Unknown route
448

449
When you try to access an API URL that does not exist you will receive 404 Not Found.
450 451

```
452
HTTP/1.1 404 Not Found
453 454
Content-Type: application/json
{
455
    "error": "404 Not Found"
456 457 458
}
```

459 460 461
## Encoding `+` in ISO 8601 dates

If you need to include a `+` in a query parameter, you may need to use `%2B` instead due
Connor Shea committed
462
a [W3 recommendation](http://www.w3.org/Addressing/URL/4_URI_Recommentations.html) that
463 464 465 466 467 468 469 470 471 472 473 474 475
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
```

476 477 478
## Clients

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

481 482
[GitLab website]: https://about.gitlab.com/applications/#api-clients "Clients using the GitLab API"
[lib-api-url]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api/api.rb
483
[ce-3749]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3749
484
[ce-5951]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951
485
[ce-9099]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9099
486
[pat]: ../user/profile/personal_access_tokens.md