Consistently format HTTP response codes in REST API documentation

Change-Id: I01425936d0af175a8712c70b5b54a927f83b8b62
This commit is contained in:
David Pursehouse
2015-01-21 11:42:32 +09:00
parent 511823f835
commit 10829f64eb
2 changed files with 19 additions and 19 deletions

View File

@@ -221,7 +221,7 @@ Retrieves the username of an account.
"john.doe" "john.doe"
---- ----
If the account does not have a username the response is `404 Not Found`. If the account does not have a username the response is "`404 Not Found`".
[[get-active]] [[get-active]]
=== Get Active === Get Active
@@ -245,7 +245,7 @@ If the account is active the string `ok` is returned.
ok ok
---- ----
If the account is inactive the response is `204 No Content`. If the account is inactive the response is "`204 No Content`".
[[set-active]] [[set-active]]
=== Set Active === Set Active
@@ -265,7 +265,7 @@ Sets the account state to active.
HTTP/1.1 201 Created HTTP/1.1 201 Created
---- ----
If the account was already active the response is `200 OK`. If the account was already active the response is "`200 OK`".
[[delete-active]] [[delete-active]]
=== Delete Active === Delete Active
@@ -285,7 +285,7 @@ Sets the account state to inactive.
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
---- ----
If the account was already inactive the response is `404 Not Found`. If the account was already inactive the response is "`404 Not Found`".
[[get-http-password]] [[get-http-password]]
=== Get HTTP Password === Get HTTP Password
@@ -310,7 +310,7 @@ Retrieves the HTTP password of an account.
"Qmxlc21ydCB1YmVyIGFsbGVzIGluIGRlciBXZWx0IQ" "Qmxlc21ydCB1YmVyIGFsbGVzIGluIGRlciBXZWx0IQ"
---- ----
If the account does not have an HTTP password the response is `404 Not Found`. If the account does not have an HTTP password the response is "`404 Not Found`".
[[set-http-password]] [[set-http-password]]
=== Set/Generate HTTP Password === Set/Generate HTTP Password
@@ -759,7 +759,7 @@ If the user has the global capability the string `ok` is returned.
---- ----
If the user doesn't have the global capability the response is If the user doesn't have the global capability the response is
`404 Not Found`. "`404 Not Found`".
.Check if you can create groups .Check if you can create groups
**** ****

View File

@@ -101,58 +101,58 @@ Here are examples that show how HTTP status codes are used in the
context of the Gerrit REST API. context of the Gerrit REST API.
==== 400 Bad Request ==== 400 Bad Request
`400 Bad Request` is returned if the request is not understood by the "`400 Bad Request`" is returned if the request is not understood by the
server due to malformed syntax. server due to malformed syntax.
E.g. `400 Bad Request` is returned if JSON input is expected but the E.g. "`400 Bad Request`" is returned if JSON input is expected but the
'Content-Type' of the request is not 'application/json' or the request 'Content-Type' of the request is not 'application/json' or the request
body doesn't contain valid JSON. body doesn't contain valid JSON.
`400 Bad Request` is also returned if required input fields are not set or "`400 Bad Request`" is also returned if required input fields are not set or
if options are set which cannot be used together. if options are set which cannot be used together.
==== 403 Forbidden ==== 403 Forbidden
`403 Forbidden` is returned if the operation is not allowed because the "`403 Forbidden`" is returned if the operation is not allowed because the
calling user does not have sufficient permissions. calling user does not have sufficient permissions.
E.g. some REST endpoints require that the calling user has certain E.g. some REST endpoints require that the calling user has certain
link:access-control.html#global_capabilities[global capabilities] link:access-control.html#global_capabilities[global capabilities]
assigned. assigned.
`403 Forbidden` is also returned if `self` is used as account ID and the "`403 Forbidden`" is also returned if `self` is used as account ID and the
REST call was done without authentication. REST call was done without authentication.
==== 404 Not Found ==== 404 Not Found
`404 Not Found` is returned if the resource that is specified by the "`404 Not Found`" is returned if the resource that is specified by the
URL is not found or is not visible to the calling user. A resource URL is not found or is not visible to the calling user. A resource
cannot be found if the URL contains a non-existing ID or view. cannot be found if the URL contains a non-existing ID or view.
==== 405 Method Not Allowed ==== 405 Method Not Allowed
`405 Method Not Allowed` is returned if the resource exists but doesn't "`405 Method Not Allowed`" is returned if the resource exists but doesn't
support the operation. support the operation.
E.g. some of the `/groups/` endpoints are only supported for Gerrit E.g. some of the `/groups/` endpoints are only supported for Gerrit
internal groups; if they are invoked for an external group the response internal groups; if they are invoked for an external group the response
is `405 Method Not Allowed`. is "`405 Method Not Allowed`".
==== 409 Conflict ==== 409 Conflict
`409 Conflict` is returned if the request cannot be completed because the "`409 Conflict`" is returned if the request cannot be completed because the
current state of the resource doesn't allow the operation. current state of the resource doesn't allow the operation.
E.g. if you try to submit a change that is abandoned, this fails with E.g. if you try to submit a change that is abandoned, this fails with
`409 Conflict` because the state of the change doesn't allow the submit "`409 Conflict`" because the state of the change doesn't allow the submit
operation. operation.
`409 Conflict` is also returned if you try to create a resource but the "`409 Conflict`" is also returned if you try to create a resource but the
name is already occupied by an existing resource. name is already occupied by an existing resource.
==== 412 Precondition Failed ==== 412 Precondition Failed
`412 Precondition Failed` is returned if a precondition from the request "`412 Precondition Failed`" is returned if a precondition from the request
header fields is not fulfilled, as described in the link:#preconditions[ header fields is not fulfilled, as described in the link:#preconditions[
Preconditions] section. Preconditions] section.
==== 422 Unprocessable Entity ==== 422 Unprocessable Entity
`422 Unprocessable Entity` is returned if the ID of a resource that is "`422 Unprocessable Entity`" is returned if the ID of a resource that is
specified in the request body cannot be resolved. specified in the request body cannot be resolved.
GERRIT GERRIT