summaryrefslogtreecommitdiff
path: root/doc/api
diff options
context:
space:
mode:
authorjubianchi <contact@jubianchi.fr>2014-08-18 20:09:09 +0200
committerjubianchi <contact@jubianchi.fr>2014-09-16 01:25:24 +0200
commit998cd3cb63d56a0058c8e519d7c20e3d6e540899 (patch)
tree38b9319858451f8bbebc7670e5505a7f1e6665e1 /doc/api
parent892371bc22813abe855f563bf4f0ee355fe067ab (diff)
downloadgitlab-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.md50
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>",
+ ...
+ ],
+ }
+ }
+ }