diff options
Diffstat (limited to 'doc/api/README.md')
| -rw-r--r-- | doc/api/README.md | 36 |
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: |