API: documentation contains infos to status codes in README file.

All the info to return codes from the API functions are available in the `README.md` file as suggested.

1 files changed, 36 insertions, 0 deletions

diff --git a/doc/api/README.md b/doc/api/README.md
index 5a662cec43b..2699434d00b 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -27,6 +27,42 @@ curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://example.com/api/v3/p
 
 The API uses JSON to serialize data. You don't need to specify `.json` at the end of API URL.
 
+
+
+## Status codes
+
+API requests return different status codes according to 
+
+The API is designed to provide status codes according to the context and how the request
+is handled. For example if a `GET` request is successful a status code `200 Ok`
+is returned. The API is designed to be RESTful.
+
+The following list gives an overview of how the API functions are designed.
+
+API request types:
+
+* `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
+* `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.
+
+
+The following list shows the possible return codes for API requests.
+
+Return values:
+
+* `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
+* `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
+* `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, a project with same name already exists
+* `500 Server Error` - While handling the request something went wrong on the server side
+
+
+
 #### Pagination
 
 When listing resources you can pass the following parameters: