diff options
author | jubianchi <contact@jubianchi.fr> | 2014-08-18 20:09:09 +0200 |
---|---|---|
committer | jubianchi <contact@jubianchi.fr> | 2014-09-16 01:25:24 +0200 |
commit | 998cd3cb63d56a0058c8e519d7c20e3d6e540899 (patch) | |
tree | 38b9319858451f8bbebc7670e5505a7f1e6665e1 /doc/api | |
parent | 892371bc22813abe855f563bf4f0ee355fe067ab (diff) | |
download | gitlab-ce-998cd3cb63d56a0058c8e519d7c20e3d6e540899.tar.gz |
Improve error reporting on users API
* users (#6878, #3526, #4209): Validation error messages are now exposed through 400 responses, 409 response are sent in case of duplicate email or username
* MRs (#5335): 409 responses are sent in case of duplicate merge request (source/target branches), 422 responses are sent when submiting MR fo/from unrelated forks
* issues
* labels
* projects
Diffstat (limited to 'doc/api')
-rw-r--r-- | doc/api/README.md | 50 |
1 files changed, 50 insertions, 0 deletions
diff --git a/doc/api/README.md b/doc/api/README.md index ababb7b6999..f76a253083f 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -80,6 +80,7 @@ Return values: - `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, e.g. creating a project with a name that already exists +- `422 Unprocessable` - The entity could not be processed - `500 Server Error` - While handling the request something went wrong on the server side ## Sudo @@ -144,3 +145,52 @@ Issue: - iid - is unique only in scope of a single project. When you browse issues or merge requests with Web UI, you see iid. So if you want to get issue with api you use `http://host/api/v3/.../issues/:id.json`. But when you want to create a link to web page - use `http:://host/project/issues/:iid.json` + +## Data validation and error reporting + +When working with the API you may encounter validation errors. In such case, the API will answer with an HTTP `400` status. +Such errors appear in two cases: + +* A required attribute of the API request is missing, e.g. the title of an issue is not given +* An attribute did not pass the validation, e.g. user bio is too long + +When an attribute is missing, you will get something like: + + HTTP/1.1 400 Bad Request + Content-Type: application/json + + { + "message":"400 (Bad request) \"title\" not given" + } + +When a validation error occurs, error messages will be different. They will hold all details of validation errors: + + HTTP/1.1 400 Bad Request + Content-Type: application/json + + { + "message": { + "bio": [ + "is too long (maximum is 255 characters)" + ] + } + } + +This makes error messages more machine-readable. The format can be described as follow: + + { + "message": { + "<property-name>": [ + "<error-message>", + "<error-message>", + ... + ], + "<embed-entity>": { + "<property-name>": [ + "<error-message>", + "<error-message>", + ... + ], + } + } + } |