BigW Consortium Gitlab

README.md 11.5 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
- [Builds](builds.md)
14
- [Build Triggers](build_triggers.md)
15 16
- [Build Variables](build_variables.md)
- [Commits](commits.md)
17
- [Deployments](deployments.md)
18 19
- [Deploy Keys](deploy_keys.md)
- [Groups](groups.md)
20 21
- [Group Access Requests](access_requests.md)
- [Group Members](members.md)
22
- [Issues](issues.md)
23
- [Keys](keys.md)
24
- [Labels](labels.md)
25
- [Merge Requests](merge_requests.md)
26
- [Milestones](milestones.md)
27
- [Open source license templates](licenses.md)
28
- [Namespaces](namespaces.md)
29
- [Notes](notes.md) (comments)
30
- [Notification settings](notification_settings.md)
31
- [Pipelines](pipelines.md)
32
- [Projects](projects.md) including setting Webhooks
33 34
- [Project Access Requests](access_requests.md)
- [Project Members](members.md)
35 36 37
- [Project Snippets](project_snippets.md)
- [Repositories](repositories.md)
- [Repository Files](repository_files.md)
38
- [Runners](runners.md)
39 40 41
- [Services](services.md)
- [Session](session.md)
- [Settings](settings.md)
42
- [Sidekiq metrics](sidekiq_metrics.md)
43 44
- [System Hooks](system_hooks.md)
- [Tags](tags.md)
45
- [Todos](todos.md)
46
- [Users](users.md)
47
- [Validate CI configuration](ci/lint.md)
48 49 50 51 52 53 54

### Internal CI API

The following documentation is for the [internal CI API](ci/README.md):

- [Builds](ci/builds.md)
- [Runners](ci/runners.md)
55

56
## Authentication
57

58
All API requests require authentication via a token. There are three types of tokens
59
available: private tokens, OAuth 2 tokens, and personal access tokens.
60

61
If a token is invalid or omitted, an error message will be returned with
62
status code `401`:
63 64 65 66 67 68 69

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

70
### Private Tokens
71

72 73
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
74 75
an underscore). You can find or reset your private token in your account page
(`/profile/account`).
76

77
### OAuth 2 Tokens
78

79 80 81 82
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:
83

84
```shell
85
curl --header "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api/v3/projects
86 87
```

88 89 90
Read more about [GitLab as an OAuth2 client](oauth2.md).

### Personal Access Tokens
91

92
> [Introduced][ce-3749] in GitLab 8.8.
93

94
You can create as many personal access tokens as you like from your GitLab
95 96
profile (`/profile/personal_access_tokens`); perhaps one for each application
that needs access to the GitLab API.
97

98 99
Once you have your token, pass it to the API using either the `private_token`
parameter or the `PRIVATE-TOKEN` header.
100 101 102 103 104 105 106

## Basic Usage

API requests should be prefixed with `api` and the API version. The API version
is defined in [`lib/api.rb`][lib-api-url].

Example of a valid API request:
107

108
```shell
109
GET https://gitlab.example.com/api/v3/projects?private_token=9koXpg98eAheJpvBs5tK
110 111
```

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

114
```shell
115
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects"
116 117
```

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

121 122
## Status codes

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

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

129
| Request type | Description |
130 131 132 133
| ------------ | ----------- |
| `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. |
| `GET` / `PUT` / `DELETE` | Return `200 OK` if the resource is accessed, modified or deleted successfully. The (modified) result is returned as JSON. |
134
| `DELETE` | Designed to be idempotent, meaning a request to a resource still returns `200 OK` even it was deleted before or is not available. The reasoning behind this, is that the user is not really interested if the resource existed before or not. |
135 136 137

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

138
| Return values | Description |
139 140 141
| ------------- | ----------- |
| `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON. |
| `201 Created` | The `POST` request was successful and the resource is returned as JSON. |
142
| `304 Not Modified` | Indicates that the resource has not been modified since the last request. |
143
| `400 Bad Request` | A required attribute of the API request is missing, e.g., the title of an issue is not given. |
144
| `401 Unauthorized` | The user is not authenticated, a valid [user token](#authentication) is necessary. |
145 146
| `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. |
147
| `405 Method Not Allowed` | The request is not supported. |
148
| `409 Conflict` | A conflicting resource already exists, e.g., creating a project with a name that already exists. |
149
| `422 Unprocessable` | The entity could not be processed. |
150
| `500 Server Error` | While handling the request something went wrong server-side. |
151

152
## Sudo
153

154
All API requests support performing an API call as if you were another user,
155
provided your private token is from an administrator account. You need to pass
156 157 158
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).
159

160 161
If a non administrative `private_token` is provided, then an error message will
be returned with status code `403`:
162 163 164

```json
{
165
  "message": "403 Forbidden - Must be admin to use sudo"
166 167 168
}
```

169
If the sudo user ID or username cannot be found, an error message will be
170
returned with status code `404`:
171 172 173 174 175 176 177

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

178 179 180 181
---

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

183 184
```shell
GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=username
185
```
186

187
```shell
188
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: username" "https://gitlab.example.com/api/v3/projects"
189 190
```

191 192
Example of a valid API call and a request using cURL with sudo request,
providing an ID:
193

194
```shell
195
GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23
196
```
197

198 199
```shell
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: 23" "https://gitlab.example.com/api/v3/projects"
200
```
201

Dmitriy Zaporozhets committed
202
## Pagination
Nihad Abbasov committed
203

204 205
Sometimes the returned result will span across many pages. When listing
resources you can pass the following parameters:
Nihad Abbasov committed
206

207 208
| Parameter | Description |
| --------- | ----------- |
209 210
| `page`    | Page number (default: `1`) |
| `per_page`| Number of items to list per page (default: `20`, max: `100`) |
Nihad Abbasov committed
211

212 213 214
In the example below, we list 50 [namespaces](namespaces.md) per page.

```bash
215
curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/namespaces?per_page=50
216 217
```

218
### Pagination Link header
219

220
[Link headers](http://www.w3.org/wiki/LinkHeader) are sent back with each
221 222
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.
223

224 225 226 227 228
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
229
curl --head --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/8/issues/8/notes?per_page=3&page=2
230 231
```

232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250
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
Link: <https://gitlab.example.com/api/v3/projects/8/issues/8/notes?page=1&per_page=3>; rel="prev", <https://gitlab.example.com/api/v3/projects/8/issues/8/notes?page=3&per_page=3>; rel="next", <https://gitlab.example.com/api/v3/projects/8/issues/8/notes?page=1&per_page=3>; rel="first", <https://gitlab.example.com/api/v3/projects/8/issues/8/notes?page=3&per_page=3>; rel="last"
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
251 252 253 254
```

### Other pagination headers

255 256 257 258 259 260 261 262 263 264
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 |
265

266
## `id` vs `iid`
Dmitriy Zaporozhets committed
267

268 269 270 271
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`.
272

273 274
| Parameter | Description |
| --------- | ----------- |
275 276
| `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
277

278
That means that if you want to get an issue via the API you should use the `id`:
279 280

```bash
281
GET /projects/42/issues/:id
282
```
Dmitriy Zaporozhets committed
283

284 285
On the other hand, if you want to create a link to a web page you should use
the `iid`:
Dmitriy Zaporozhets committed
286

287
```bash
288
GET /projects/42/issues/:iid
289
```
290 291 292

## Data validation and error reporting

293
When working with the API you may encounter validation errors, in which case
294 295
the API will answer with an HTTP `400` status.

296 297
Such errors appear in two cases:

298
- A required attribute of the API request is missing, e.g., the title of an
299
  issue is not given
300
- An attribute did not pass the validation, e.g., user bio is too long
301 302 303

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

304
```
305 306 307 308 309 310
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "message":"400 (Bad request) \"title\" not given"
}
```
311

312 313
When a validation error occurs, error messages will be different. They will
hold all details of validation errors:
314

315
```
316 317 318 319 320 321 322
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "message": {
        "bio": [
            "is too long (maximum is 255 characters)"
        ]
323
    }
324 325
}
```
326

327 328
This makes error messages more machine-readable. The format can be described as
follows:
329

330 331 332 333 334 335 336 337 338
```json
{
    "message": {
        "<property-name>": [
            "<error-message>",
            "<error-message>",
            ...
        ],
        "<embed-entity>": {
339 340 341 342 343 344 345
            "<property-name>": [
                "<error-message>",
                "<error-message>",
                ...
            ],
        }
    }
346 347 348 349 350 351
}
```

## Clients

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

354 355
[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
356
[ce-3749]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3749