From b10341ce3f6f0c0eac4e28eb1ccba44cdfd40d29 Mon Sep 17 00:00:00 2001 From: Chris Yeoh Date: Fri, 28 Mar 2014 09:51:18 +1030 Subject: [PATCH] Adds more API error return code requirements Adds information about the reason that error codes can be returned by a method. This will help ensure that people consider more of the semantics (especially the error paths) of new API methods. Change-Id: Ia2ff1fd2e689f5c0fad0a84e807de07d150ae9ee --- specs/template.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/specs/template.rst b/specs/template.rst index a8f45f41c..e6d0fba11 100644 --- a/specs/template.rst +++ b/specs/template.rst @@ -86,6 +86,14 @@ Each API method which is either added or changed should have the following * Method type (POST/PUT/GET/DELETE) * Normal http response code(s) * Expected error http response code(s) + + * A description for each possible error code should be included + describing semantic errors which can cause it such as + inconsistent parameters supplied to the method, or when an + instance is not in an appropriate state for the request to + succeed. Errors caused by syntactic problems covered by the JSON + schema defintion do not need to be included. + * URL for the resource * Parameters which can be passed via the url * JSON schema definition for the body data if allowed