Add mutation payloads section
@@ -33,7 +33,11 @@ In this example we have the following elements:
``Mutation`` type with two mutations: ``login`` mutation that requires username and password strings and returns bool with status, and ``logout`` that takes no arguments and just returns status.
-For the sake of simplicity, our mutations return bools, but really there is no such restriction. In fact, it is recommended for mutations to return dedicated ``Payload`` types::
+
+Mutation payloads
+-----------------
+
+For the sake of simplicity, our mutations return bools, but really there is no such requirement. In fact, it is generally considered a good practice for mutations to return dedicated ``payload`` types containing additional information about the result, such as errors or updated object::
type_def = """
type Mutation {
@@ -49,6 +53,7 @@ For the sake of simplicity, our mutations return bools, but really there is no s
Above mutation will return special type containing information about mutation's status, as well as either ``Error`` message or logged in ``User``.
+
Writing resolvers
-----------------
