Commit 6fffc207 authored by Jeroen van Baarsen's avatar Jeroen van Baarsen

Merge pull request #7511 from jbrooksuk/api-docs

Consistency, spelling and grammar
parents cb33279a 3f36f84c
...@@ -31,7 +31,7 @@ ...@@ -31,7 +31,7 @@
## Introduction ## Introduction
All API requests require authentication. You need to pass a `private_token` parameter by url or header. If passed as header, the header name must be "PRIVATE-TOKEN" (capital and with dash instead of underscore). You can find or reset your private token in your profile. All API requests require authentication. You need to pass a `private_token` parameter by URL or header. If passed as header, the header name must be "PRIVATE-TOKEN" (capital and with dash instead of underscore). You can find or reset your private token in your profile.
If no, or an invalid, `private_token` is provided then an error message will be returned with status code 401: If no, or an invalid, `private_token` is provided then an error message will be returned with status code 401:
...@@ -65,14 +65,14 @@ API request types: ...@@ -65,14 +65,14 @@ API request types:
- `GET` requests access one or more resources and return the result as JSON - `GET` requests access one or more resources and return the result as JSON
- `POST` requests return `201 Created` if the resource is successfully created and return the newly created resource as JSON - `POST` requests return `201 Created` if the resource is successfully created and return the newly created resource as JSON
- `GET`, `PUT` and `DELETE` return `200 Ok` if the resource is accessed, modified or deleted successfully, the (modified) result is returned as JSON - `GET`, `PUT` and `DELETE` return `200 OK` if the resource is accessed, modified or deleted successfully, the (modified) result is returned as JSON
- `DELETE` requests are designed to be idempotent, meaning a request 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` requests are designed to be idempotent, meaning a request 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.
The following list shows the possible return codes for API requests. The following list shows the possible return codes for API requests.
Return values: Return values:
- `200 Ok` - The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON - `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 - `201 Created` - The `POST` request was successful and the resource is returned as JSON
- `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, e.g. the title of an issue is not given
- `401 Unauthorized` - The user is not authenticated, a valid user token is necessary, see above - `401 Unauthorized` - The user is not authenticated, a valid user token is necessary, see above
......
...@@ -85,7 +85,7 @@ Parameters: ...@@ -85,7 +85,7 @@ Parameters:
## Protect repository branch ## Protect repository branch
Protects a single project repository branch. This is an idempotent function, protecting an already Protects a single project repository branch. This is an idempotent function, protecting an already
protected repository branch still returns a `200 Ok` status code. protected repository branch still returns a `200 OK` status code.
``` ```
PUT /projects/:id/repository/branches/:branch/protect PUT /projects/:id/repository/branches/:branch/protect
...@@ -126,7 +126,7 @@ Parameters: ...@@ -126,7 +126,7 @@ Parameters:
## Unprotect repository branch ## Unprotect repository branch
Unprotects a single project repository branch. This is an idempotent function, unprotecting an already Unprotects a single project repository branch. This is an idempotent function, unprotecting an already
unprotected repository branch still returns a `200 Ok` status code. unprotected repository branch still returns a `200 OK` status code.
``` ```
PUT /projects/:id/repository/branches/:branch/unprotect PUT /projects/:id/repository/branches/:branch/unprotect
......
...@@ -196,13 +196,13 @@ If an error occurs, an error number and a message explaining the reason is retur ...@@ -196,13 +196,13 @@ If an error occurs, an error number and a message explaining the reason is retur
Merge changes submitted with MR using this API. Merge changes submitted with MR using this API.
If merge success you get 200 OK. If merge success you get `200 OK`.
If it has some conflicts and can not be merged - you get 405 and error message 'Branch cannot be merged' If it has some conflicts and can not be merged - you get 405 and error message 'Branch cannot be merged'
If merge request is already merged or closed - you get 405 and error message 'Method Not Allowed' If merge request is already merged or closed - you get 405 and error message 'Method Not Allowed'
If you dont have permissions to accept this merge request - you get 401 If you don't have permissions to accept this merge request - you'll get a 401
``` ```
PUT /projects/:id/merge_request/:merge_request_id/merge PUT /projects/:id/merge_request/:merge_request_id/merge
......
...@@ -78,7 +78,7 @@ Parameters: ...@@ -78,7 +78,7 @@ Parameters:
## Delete snippet ## Delete snippet
Deletes an existing project snippet. This is an idempotent function and deleting a non-existent Deletes an existing project snippet. This is an idempotent function and deleting a non-existent
snippet still returns a `200 Ok` status code. snippet still returns a `200 OK` status code.
``` ```
DELETE /projects/:id/snippets/:snippet_id DELETE /projects/:id/snippets/:snippet_id
......
...@@ -59,7 +59,7 @@ Parameters: ...@@ -59,7 +59,7 @@ Parameters:
## Delete system hook ## Delete system hook
Deletes a system hook. This is an idempotent API function and returns `200 Ok` even if the hook is not available. If the hook is deleted it is also returned as JSON. Deletes a system hook. This is an idempotent API function and returns `200 OK` even if the hook is not available. If the hook is deleted it is also returned as JSON.
``` ```
DELETE /hooks/:id DELETE /hooks/:id
......
...@@ -202,7 +202,7 @@ e.g. when renaming the email address to some existing one. ...@@ -202,7 +202,7 @@ e.g. when renaming the email address to some existing one.
Deletes a user. Available only for administrators. Deletes a user. Available only for administrators.
This is an idempotent function, calling this function for a non-existent user id This is an idempotent function, calling this function for a non-existent user id
still returns a status code `200 Ok`. still returns a status code `200 OK`.
The JSON response differs if the user was actually deleted or not. The JSON response differs if the user was actually deleted or not.
In the former the user is returned and in the latter not. In the former the user is returned and in the latter not.
...@@ -336,7 +336,7 @@ Will return created key with status `201 Created` on success, or `404 Not found` ...@@ -336,7 +336,7 @@ Will return created key with status `201 Created` on success, or `404 Not found`
Deletes key owned by currently authenticated user. Deletes key owned by currently authenticated user.
This is an idempotent function and calling it on a key that is already deleted This is an idempotent function and calling it on a key that is already deleted
or not available results in `200 Ok`. or not available results in `200 OK`.
``` ```
DELETE /user/keys/:id DELETE /user/keys/:id
...@@ -359,4 +359,4 @@ Parameters: ...@@ -359,4 +359,4 @@ Parameters:
- `uid` (required) - id of specified user - `uid` (required) - id of specified user
- `id` (required) - SSH key ID - `id` (required) - SSH key ID
Will return `200 Ok` on success, or `404 Not found` if either user or key cannot be found. Will return `200 OK` on success, or `404 Not found` if either user or key cannot be found.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment