/doc/api/README.md
Markdown | 326 lines | 251 code | 75 blank | 0 comment | 0 complexity | 3ce800b05ac12693dbd8167305aa6407 MD5 | raw file
- # GitLab API
- Automate GitLab via a simple and powerful API. All definitions can be found
- under [`/lib/api`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api).
- ## Resources
- Documentation for various API resources can be found separately in the
- following locations:
- - [Users](users.md)
- - [Session](session.md)
- - [Projects](projects.md) including setting Webhooks
- - [Project Snippets](project_snippets.md)
- - [Services](services.md)
- - [Repositories](repositories.md)
- - [Repository Files](repository_files.md)
- - [Commits](commits.md)
- - [Tags](tags.md)
- - [Branches](branches.md)
- - [Merge Requests](merge_requests.md)
- - [Issues](issues.md)
- - [Labels](labels.md)
- - [Milestones](milestones.md)
- - [Notes](notes.md) (comments)
- - [Deploy Keys](deploy_keys.md)
- - [System Hooks](system_hooks.md)
- - [Groups](groups.md)
- - [Namespaces](namespaces.md)
- - [Settings](settings.md)
- - [Keys](keys.md)
- - [Builds](builds.md)
- - [Build triggers](build_triggers.md)
- - [Build Variables](build_variables.md)
- - [Runners](runners.md)
- - [Open source license templates](licenses.md)
- - [EE License](license.md)
- ## Authentication
- All API requests require 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).
- You can find or reset your private token in your account page (`/profile/account`).
- If `private_token` is invalid or omitted, then an error message will be
- returned with status code `401`:
- ```json
- {
- "message": "401 Unauthorized"
- }
- ```
- 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:
- ```shell
- GET https://gitlab.example.com/api/v3/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/v3/projects"
- ```
- The API uses JSON to serialize data. You don't need to specify `.json` at the
- end of an API URL.
- ## Authentication with OAuth2 token
- Instead of the `private_token` you can transmit the OAuth2 access token as a
- header or as a parameter.
- Example of OAuth2 token as a parameter:
- ```shell
- curl https://gitlab.example.com/api/v3/user?access_token=OAUTH-TOKEN
- ```
- Example of OAuth2 token as a header:
- ```shell
- curl -H "Authorization: Bearer OAUTH-TOKEN" https://example.com/api/v3/user
- ```
- Read more about [GitLab as an OAuth2 client](oauth2.md).
- ## 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. |
- | `GET` / `PUT` / `DELETE` | Return `200 OK` if the resource is accessed, modified or deleted successfully. The (modified) result is returned as JSON. |
- | `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. |
- 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. |
- | `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. |
- | `422 Unprocessable` | The entity could not be processed. |
- | `500 Server Error` | While handling the request something went wrong server-side. |
- ## Sudo
- All API requests support performing an API call as if you were another user,
- provided your private token is from an administrator account. You need to pass
- 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).
- If a non administrative `private_token` is provided, then an error message will
- be returned with status code `403`:
- ```json
- {
- "message": "403 Forbidden: Must be admin to use sudo"
- }
- ```
- If the sudo user ID or username cannot be found, an error message will be
- returned with status code `404`:
- ```json
- {
- "message": "404 Not Found: No user id or username for: <id/username>"
- }
- ```
- ---
- Example of a valid API call and a request using cURL with sudo request,
- providing a username:
- ```shell
- GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=username
- ```
- ```shell
- curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: username" "https://gitlab.example.com/api/v3/projects"
- ```
- Example of a valid API call and a request using cURL with sudo request,
- providing an ID:
- ```shell
- GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23
- ```
- ```shell
- curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: 23" "https://gitlab.example.com/api/v3/projects"
- ```
- ## Pagination
- Sometimes the returned result will span across many pages. When listing
- resources you can pass the following parameters:
- | Parameter | Description |
- | --------- | ----------- |
- | `page` | Page number (default: `1`) |
- | `per_page`| Number of items to list per page (default: `20`, max: `100`) |
- In the example below, we list 50 [namespaces](namespaces.md) per page.
- ```bash
- curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/namespaces?per_page=50
- ```
- ### Pagination Link header
- [Link headers](http://www.w3.org/wiki/LinkHeader) are sent back with each
- 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.
- 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
- curl -I -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/8/issues/8/notes?per_page=3&page=2
- ```
- 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
- ```
- ### Other pagination headers
- 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 |
- ## `id` vs `iid`
- 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`.
- | Parameter | Description |
- | --------- | ----------- |
- | `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` |
- That means that if you want to get an issue via the API you should use the `id`:
- ```bash
- GET /projects/42/issues/:id
- ```
- On the other hand, if you want to create a link to a web page you should use
- the `iid`:
- ```bash
- GET /projects/42/issues/:iid
- ```
- ## Data validation and error reporting
- When working with the API you may encounter validation errors, in which case
- the API will answer with an HTTP `400` status.
- Such errors appear in two cases:
- - A required attribute of the API request is missing, e.g., the title of an
- issue is not given
- - An attribute did not pass the validation, e.g., user bio is too long
- When an attribute is missing, you will get something like:
- ```
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
- {
- "message":"400 (Bad request) \"title\" not given"
- }
- ```
- When a validation error occurs, error messages will be different. They will
- hold all details of validation errors:
- ```
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
- {
- "message": {
- "bio": [
- "is too long (maximum is 255 characters)"
- ]
- }
- }
- ```
- This makes error messages more machine-readable. The format can be described as
- follows:
- ```json
- {
- "message": {
- "<property-name>": [
- "<error-message>",
- "<error-message>",
- ...
- ],
- "<embed-entity>": {
- "<property-name>": [
- "<error-message>",
- "<error-message>",
- ...
- ],
- }
- }
- }
- ```
- ## Clients
- There are many unofficial GitLab API Clients for most of the popular
- programming languages. Visit the [GitLab website] for a complete list.
- [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