The API uses JSON to serialize data. You don't need to specify `.json` at the end of API URL.
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
...
...
@@ -82,21 +89,21 @@ 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
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 | Explanation |
| 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 it is the user is not really interested if the resource existed before or not. |
| `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 | Explanation |
| 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. |
...
...
@@ -107,15 +114,15 @@ The following table shows the possible return codes for API requests.
| `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 on the server side. |
| `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 administration account. You need to pass
the `sudo` parameter by URL or header with an ID or username of the user you
want to perform the operation as. If passed as a header, the header name must
be **SUDO** (capitals).
provided your private token is from an administrator account. You need to pass
the `sudo` parameter either by URL 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** (capitals).
If a non administrative `private_token` is provided, then an error message will
be returned with status code `403`:
...
...
@@ -135,22 +142,24 @@ returned with status code `404`:
}
```
Example of a valid API call with sudo request providing a username and an ID
respectively:
---
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
GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23
