Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Support
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
G
gitlab-ce
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
0
Issues
0
List
Boards
Labels
Milestones
Merge Requests
1
Merge Requests
1
Analytics
Analytics
Repository
Value Stream
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Commits
Issue Boards
Open sidebar
nexedi
gitlab-ce
Commits
c8b21732
Commit
c8b21732
authored
Nov 18, 2020
by
Mike Jang
Browse files
Options
Browse Files
Download
Plain Diff
Merge branch 'eread/edit-api-landing-page' into 'master'
Edit API landing page See merge request gitlab-org/gitlab!47989
parents
41f446a0
1007d4f5
Changes
1
Hide whitespace changes
Inline
Side-by-side
Showing
1 changed file
with
16 additions
and
16 deletions
+16
-16
doc/api/README.md
doc/api/README.md
+16
-16
No files found.
doc/api/README.md
View file @
c8b21732
...
@@ -97,7 +97,7 @@ HTTP/2 200
...
@@ -97,7 +97,7 @@ HTTP/2 200
This can help you investigate an unexpected response.
This can help you investigate an unexpected response.
### API
R
equest that includes the exit code
### API
r
equest that includes the exit code
If you want to expose the HTTP exit code, include the
`--fail`
option:
If you want to expose the HTTP exit code, include the
`--fail`
option:
...
@@ -110,8 +110,8 @@ The HTTP exit code can help you diagnose the success or failure of your REST cal
...
@@ -110,8 +110,8 @@ The HTTP exit code can help you diagnose the success or failure of your REST cal
## Authentication
## Authentication
Most API requests require authentication, or
will return public data only
when
Most API requests require authentication, or
only return public data
when
authentication isn't provided. For cases where it isn't required, this
will be
authentication isn't provided. For cases where it isn't required, this
is
mentioned in the documentation for each individual endpoint (for example, the
mentioned in the documentation for each individual endpoint (for example, the
[
`/projects/:id` endpoint
](
projects.md#get-single-project
)
).
[
`/projects/:id` endpoint
](
projects.md#get-single-project
)
).
...
@@ -133,7 +133,7 @@ to build applications or scripts that do so, the following options are available
...
@@ -133,7 +133,7 @@ to build applications or scripts that do so, the following options are available
-
[
Impersonation tokens
](
#impersonation-tokens
)
-
[
Impersonation tokens
](
#impersonation-tokens
)
-
[
Sudo
](
#sudo
)
-
[
Sudo
](
#sudo
)
If authentication information is invalid or omitted, GitLab
will return
an error
If authentication information is invalid or omitted, GitLab
returns
an error
message with a status code of
`401`
:
message with a status code of
`401`
:
```
json
```
json
...
@@ -221,13 +221,13 @@ The token is valid as long as the job is running.
...
@@ -221,13 +221,13 @@ The token is valid as long as the job is running.
### Impersonation tokens
### Impersonation tokens
Impersonation tokens are a type of
[
personal access token
](
../user/profile/personal_access_tokens.md
)
Impersonation tokens are a type of
[
personal access token
](
../user/profile/personal_access_tokens.md
)
that can only be created by an admin for a specific user. They are a great fit
that can only be created by an admin
istrator
for a specific user. They are a great fit
if you want to build applications or scripts that authenticate with the API as a
if you want to build applications or scripts that authenticate with the API as a
specific user.
specific user.
They're an alternative to directly using the user's password or one of their
They're an alternative to directly using the user's password or one of their
personal access tokens, and to using the
[
Sudo
](
#sudo
)
feature, as the user's
personal access tokens, and to using the
[
Sudo
](
#sudo
)
feature, as the user's
(or admin
's,
in the case of Sudo) password or token may not be known, or may
(or admin
istrator's
in the case of Sudo) password or token may not be known, or may
change over time.
change over time.
For more information, see the
[
users API
](
users.md#create-an-impersonation-token
)
For more information, see the
[
users API
](
users.md#create-an-impersonation-token
)
...
@@ -292,7 +292,7 @@ message with a status code of `403`:
...
@@ -292,7 +292,7 @@ message with a status code of `403`:
}
}
```
```
If an access token without the
`sudo`
scope is provided, an error message
will
If an access token without the
`sudo`
scope is provided, an error message
is
be returned with a status code of
`403`
:
be returned with a status code of
`403`
:
```
json
```
json
...
@@ -303,7 +303,7 @@ be returned with a status code of `403`:
...
@@ -303,7 +303,7 @@ be returned with a status code of `403`:
}
}
```
```
If the sudo user ID or username cannot be found, an error message
will be
If the sudo user ID or username cannot be found, an error message
is
returned with a status code of
`404`
:
returned with a status code of
`404`
:
```
json
```
json
...
@@ -357,7 +357,7 @@ The following table shows the possible return codes for API requests.
...
@@ -357,7 +357,7 @@ The following table shows the possible return codes for API requests.
|
`204 No Content`
| The server has successfully fulfilled the request and that there is no additional content to send in the response payload body. |
|
`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. |
|
`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. |
|
`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. |
|
`400 Bad Request`
| A required attribute of the API request is missing
. For example
, the title of an issue is not given. |
|
`401 Unauthorized`
| The user is not authenticated, a valid
[
user token
](
#authentication
)
is necessary. |
|
`401 Unauthorized`
| The user is not authenticated, a valid
[
user token
](
#authentication
)
is necessary. |
|
`403 Forbidden`
| The request is not allowed. For example, the user is not allowed to delete a project. |
|
`403 Forbidden`
| The request is not allowed. For example, the user is not allowed to delete a project. |
|
`404 Not Found`
| A resource could not be accessed. For example, an ID for a resource could not be found. |
|
`404 Not Found`
| A resource could not be accessed. For example, an ID for a resource could not be found. |
...
@@ -411,7 +411,7 @@ of the issue with ID `8` which belongs to the project with ID `9`:
...
@@ -411,7 +411,7 @@ of the issue with ID `8` which belongs to the project with ID `9`:
curl
--head
--header
"PRIVATE-TOKEN: <your_access_token>"
"https://gitlab.example.com/api/v4/projects/9/issues/8/notes?per_page=3&page=2"
curl
--head
--header
"PRIVATE-TOKEN: <your_access_token>"
"https://gitlab.example.com/api/v4/projects/9/issues/8/notes?per_page=3&page=2"
```
```
The response
will then be
:
The response
is
:
```
http
```
http
HTTP/2 200 OK
HTTP/2 200 OK
...
@@ -479,7 +479,7 @@ Status: 200 OK
...
@@ -479,7 +479,7 @@ Status: 200 OK
```
```
CAUTION:
**Deprecation:**
CAUTION:
**Deprecation:**
The
`Links`
header
will
be removed in GitLab 14.0 to be aligned with the
The
`Links`
header
is scheduled to
be removed in GitLab 14.0 to be aligned with the
[
W3C `Link` specification
](
https://www.w3.org/wiki/LinkHeader
)
. The
`Link`
[
W3C `Link` specification
](
https://www.w3.org/wiki/LinkHeader
)
. The
`Link`
header was
[
added in GitLab 13.1
](
https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33714
)
header was
[
added in GitLab 13.1
](
https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33714
)
and should be used instead.
and should be used instead.
...
@@ -525,8 +525,8 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git
...
@@ -525,8 +525,8 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git
```
```
Path parameters that are required to be URL-encoded must be followed. If not,
Path parameters that are required to be URL-encoded must be followed. If not,
it
won't match an API endpoint, and will respond
with a 404. If there's
it
doesn't match an API endpoint and responds
with a 404. If there's
something in front of the API (for example, Apache), ensure that it
wo
n't decode
something in front of the API (for example, Apache), ensure that it
does
n't decode
the URL-encoded path parameters.
the URL-encoded path parameters.
## Namespaced path encoding
## Namespaced path encoding
...
@@ -657,7 +657,7 @@ Such errors appear in the following cases:
...
@@ -657,7 +657,7 @@ Such errors appear in the following cases:
-
An attribute did not pass the validation (for example, the user bio is too
-
An attribute did not pass the validation (for example, the user bio is too
long).
long).
When an attribute is missing, you
will get
something like:
When an attribute is missing, you
receive
something like:
```
http
```
http
HTTP
/
1.1
400
Bad Request
HTTP
/
1.1
400
Bad Request
...
@@ -667,7 +667,7 @@ Content-Type: application/json
...
@@ -667,7 +667,7 @@ Content-Type: application/json
}
}
```
```
When a validation error occurs, error messages
will be different. They will
hold
When a validation error occurs, error messages
are different. They
hold
all details of validation errors:
all details of validation errors:
```
http
```
http
...
@@ -706,7 +706,7 @@ follows:
...
@@ -706,7 +706,7 @@ follows:
## Unknown route
## Unknown route
When you attempt to access an API URL that doesn't exist, you
will receive
When you attempt to access an API URL that doesn't exist, you
receive a
404 Not Found message.
404 Not Found message.
```
http
```
http
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment