Merge lp:~julian-edwards/maas/api-doc-bug-1391193 into lp:~maas-committers/maas/trunk

[Julian Edwards]

Clarify return codes used in all the API docstrings.

I've not covered ValidationError yet, I want to make sure it always returns a 400.

[Newell Jensen (newell-jensen)]

Approve. See inline comments.

review: Approve

[Julian Edwards (julian-edwards)]

Gosh darn I thought I had fixed those, thanks for spotting!

[MAAS Lander (maas-lander)]

The attempt to merge lp:~julian-edwards/maas/api-doc-bug-1391193 into lp:maas failed. Below is the output from the failed tests.

Ign http://security.ubuntu.com trusty-security InRelease
Hit http://security.ubuntu.com trusty-security Release.gpg
Hit http://security.ubuntu.com trusty-security Release
Ign http://nova.clouds.archive.ubuntu.com trusty InRelease
Ign http://nova.clouds.archive.ubuntu.com trusty-updates InRelease
Hit http://nova.clouds.archive.ubuntu.com trusty Release.gpg
Hit http://nova.clouds.archive.ubuntu.com trusty-updates Release.gpg
Hit http://nova.clouds.archive.ubuntu.com trusty Release
Hit http://nova.clouds.archive.ubuntu.com trusty-updates Release
Hit http://security.ubuntu.com trusty-security/main Sources
Hit http://security.ubuntu.com trusty-security/universe Sources
Hit http://nova.clouds.archive.ubuntu.com trusty/main Sources
Hit http://security.ubuntu.com trusty-security/main amd64 Packages
Hit http://security.ubuntu.com trusty-security/universe amd64 Packages
Hit http://nova.clouds.archive.ubuntu.com trusty/universe Sources
Hit http://security.ubuntu.com trusty-security/main Translation-en
Hit http://nova.clouds.archive.ubuntu.com trusty/main amd64 Packages
Hit http://security.ubuntu.com trusty-security/universe Translation-en
Hit http://nova.clouds.archive.ubuntu.com trusty/universe amd64 Packages
Hit http://nova.clouds.archive.ubuntu.com trusty/main Translation-en
Hit http://nova.clouds.archive.ubuntu.com trusty/universe Translation-en
Ign http://nova.clouds.archive.ubuntu.com trusty/main Translation-en_US
Ign http://nova.clouds.archive.ubuntu.com trusty/universe Translation-en_US
Hit http://nova.clouds.archive.ubuntu.com trusty-updates/main Sources
Hit http://nova.clouds.archive.ubuntu.com trusty-updates/universe Sources
Hit http://nova.clouds.archive.ubuntu.com trusty-updates/main amd64 Packages
Hit http://nova.clouds.archive.ubuntu.com trusty-updates/universe amd64 Packages
Hit http://nova.clouds.archive.ubuntu.com trusty-updates/main Translation-en
Hit http://nova.clouds.archive.ubuntu.com trusty-updates/universe Translation-en
Reading package lists...
sudo DEBIAN_FRONTEND=noninteractive apt-get -y \
     --no-install-recommends install apache2 authbind bind9 bind9utils build-essential bzr-builddeb curl daemontools debhelper dh-apport distro-info dnsutils firefox freeipmi-tools gjs ipython isc-dhcp-common libjs-raphael libjs-yui3-full libjs-yui3-min libpq-dev make pep8 postgresql pyflakes python-amqplib python-bzrlib python-celery python-convoy python-crochet python-cssselect python-curtin python-dev python-distro-info python-django python-django-piston python-django-south python-djorm-ext-pgarray python-docutils python-extras python-fixtures python-flake8 python-formencode python-hivex python-httplib2 python-jinja2 python-jsonschema python-lockfile python-lxml python-mimeparse python-mock python-netaddr python-netifaces python-nose python-oauth python-oops python-oops-amqp python-oops-datedir-repo python-oops-twisted python-oops-wsgi python-openssl python-paramiko python-pexpect python-pip python-pocket-lint python-psycopg2 python-pyinotify python-seamicroclient python-simplejson python-simplestreams python...

=== modified file 'src/maasserver/api/files.py'
--- src/maasserver/api/files.py	2014-08-16 10:34:55 +0000
+++ src/maasserver/api/files.py	2014-11-24 18:23:46 +0000
@@ -184,6 +184,11 @@
         :type filename: string
         :param file: Actual file data with content type
             application/octet-stream
+
+        Returns 400 if any of these conditions apply:
+         - The filename is missing from the parameters
+         - The file data is missing
+         - More than one file is supplied
         """
         filename = request.data.get("filename", None)
         if not filename:
 
=== modified file 'src/maasserver/api/ip_addresses.py'
--- src/maasserver/api/ip_addresses.py	2014-10-22 10:35:09 +0000
+++ src/maasserver/api/ip_addresses.py	2014-11-24 18:23:46 +0000
@@ -79,6 +79,9 @@
         :param network: CIDR representation of the network on which the IP
             reservation is required. e.g. 10.1.2.0/24
         :type network: unicode
+
+        Returns 400 if there is no network in MAAS matching the provided one.
+        Returns 503 if there are no more IP addresses available.
         """
         network = get_mandatory_param(request.POST, "network")
         requested_address = get_optional_param(
@@ -111,6 +114,8 @@
 
         :param ip: The IP address to release.
         :type ip: unicode
+
+        Returns 404 if the provided IP address is not found.
         """
         ip = get_mandatory_param(request.POST, "ip")
         staticaddress = get_object_or_404(
 
=== modified file 'src/maasserver/api/node_group_interfaces.py'
--- src/maasserver/api/node_group_interfaces.py	2014-09-10 16:20:31 +0000
+++ src/maasserver/api/node_group_interfaces.py	2014-11-24 18:23:46 +0000
@@ -94,6 +94,10 @@
         :param static_ip_range_high: Highest static IP address to assign to
             clients.
         :type static_ip_range_high: unicode (IP Address)
+
+        Returns 404 if the node group (cluster) is not found.
+        Returns 403 if the user does not have permission to access the
+        interface.
         """
         nodegroup = get_object_or_404(NodeGroup, uuid=uuid)
         if not request.user.is_superuser:
@@ -139,7 +143,10 @@
         return nodegroupinterface
 
     def read(self, request, uuid, name):
-        """List of NodeGroupInterfaces of a NodeGroup."""
+        """List of NodeGroupInterfaces of a NodeGroup.
+
+        Returns 404 if the nodegroup (cluster) is not found.
+        """
         # Read-only access is allowed to any user.
         nodegroup = get_object_or_404(NodeGroup, uuid=uuid)
         return get_object_or_404(
@@ -171,6 +178,10 @@
         :param static_ip_range_high: Highest static IP address to assign to
             clients.
         :type static_ip_range_high: unicode (IP Address)
+
+        Returns 404 if the nodegroup (cluster) is not found.
+        Returns 403 if the user does not have permission to access the
+        interface.
         """
         nodegroupinterface = self.get_interface(request, uuid, name)
         form = NodeGroupInterfaceForm(
@@ -181,7 +192,12 @@
             raise ValidationError(form.errors)
 
     def delete(self, request, uuid, name):
-        """Delete a specific NodeGroupInterface."""
+        """Delete a specific NodeGroupInterface.
+
+        Returns 404 if the nodegroup (cluster) is not found.
+        Returns 403 if the user does not have permission to access the
+        interface.
+        """
         nodegroupinterface = self.get_interface(request, uuid, name)
         nodegroupinterface.delete()
         return rc.DELETED
 
=== modified file 'src/maasserver/api/node_groups.py'
--- src/maasserver/api/node_groups.py	2014-10-09 20:24:04 +0000
+++ src/maasserver/api/node_groups.py	2014-11-24 18:23:46 +0000
@@ -92,7 +92,10 @@
         :param uuid: The UUID (or list of UUIDs) of the nodegroup(s) to accept.
         :type name: unicode (or list of unicodes)
 
-        This method is reserved to admin users.
+        This method is reserved to admin users and returns 403 if the
+        user is not an admin.
+
+        Returns 404 if the nodegroup (cluster) is not found.
         """
         uuids = request.data.getlist('uuid')
         for uuid in uuids:
@@ -125,7 +128,10 @@
         :param uuid: The UUID (or list of UUIDs) of the nodegroup(s) to reject.
         :type name: unicode (or list of unicodes)
 
-        This method is reserved to admin users.
+        This method is reserved to admin users and returns 403 if the
+        user is not an admin.
+
+        Returns 404 if the nodegroup (cluster) is not found.
         """
         uuids = request.data.getlist('uuid')
         for uuid in uuids:
@@ -173,7 +179,10 @@
     fields = DISPLAYED_NODEGROUP_FIELDS
 
     def read(self, request, uuid):
-        """GET a node group."""
+        """GET a node group.
+
+        Returns 404 if the nodegroup (cluster) is not found.
+        """
         return get_object_or_404(NodeGroup, uuid=uuid)
 
     @classmethod
@@ -195,6 +204,8 @@
         :param status: The new status for this cluster (see
             vocabulary `NODEGROUP_STATUS`).
         :type status: int
+
+        Returns 404 if the nodegroup (cluster) is not found.
         """
         nodegroup = get_object_or_404(NodeGroup, uuid=uuid)
         form = NodeGroupEdit(instance=nodegroup, data=request.data)
@@ -206,7 +217,10 @@
     @admin_method
     @operation(idempotent=False)
     def import_boot_images(self, request, uuid):
-        """Import the pxe files on this cluster controller."""
+        """Import the pxe files on this cluster controller.
+
+        Returns 404 if the nodegroup (cluster) is not found.
+        """
         nodegroup = get_object_or_404(NodeGroup, uuid=uuid)
         nodegroup.import_boot_images()
         return HttpResponse(
@@ -215,7 +229,10 @@
 
     @operation(idempotent=True)
     def list_nodes(self, request, uuid):
-        """Get the list of node ids that are part of this group."""
+        """Get the list of node ids that are part of this group.
+
+        Returns 404 if the nodegroup (cluster) is not found.
+        """
         nodegroup = get_object_or_404(NodeGroup, uuid=uuid)
         if not request.user.is_superuser:
             check_nodegroup_access(request, nodegroup)
@@ -250,6 +267,8 @@
         b) Requests for nodes that are not part of the nodegroup are
            just ignored.
 
+        Returns 404 if the nodegroup (cluster) is not found.
+        Returns 403 if the user does not have access to the nodegroup.
         """
         nodegroup = get_object_or_404(NodeGroup, uuid=uuid)
         if not request.user.is_superuser:
@@ -318,6 +337,10 @@
         :param error: Optional error string.  A download that has submitted an
             error with its last progress report is considered to have failed.
         :type error: unicode
+
+        Returns 404 if the nodegroup (cluster) is not found.
+        Returns 403 if the user does not have access to the nodegroup.
+        Returns 400 if the required parameters were not passed.
         """
         nodegroup = get_object_or_404(NodeGroup, uuid=uuid)
         check_nodegroup_access(request, nodegroup)
@@ -372,6 +395,10 @@
         :param power_pass: The password to use, when qemu+ssh is given as a
             connection string and ssh key authentication is not being used.
         :type power_pass: unicode
+
+        Returns 404 if the nodegroup (cluster) is not found.
+        Returns 403 if the user does not have access to the nodegroup.
+        Returns 400 if the required parameters were not passed.
         """
         nodegroup = get_object_or_404(NodeGroup, uuid=uuid)
 
@@ -409,6 +436,9 @@
         :param password: The password for the API.
         :type password: unicode
 
+        Returns 404 if the nodegroup (cluster) is not found.
+        Returns 403 if the user does not have access to the nodegroup.
+        Returns 400 if the required parameters were not passed.
         """
         nodegroup = get_object_or_404(NodeGroup, uuid=uuid)
 
@@ -432,6 +462,9 @@
         :param password: The password for the MSCM.
         :type password: unicode
 
+        Returns 404 if the nodegroup (cluster) is not found.
+        Returns 403 if the user does not have access to the nodegroup.
+        Returns 400 if the required parameters were not passed.
         """
         nodegroup = get_object_or_404(NodeGroup, uuid=uuid)
 
 
=== modified file 'src/maasserver/api/node_macs.py'
--- src/maasserver/api/node_macs.py	2014-08-18 13:27:34 +0000
+++ src/maasserver/api/node_macs.py	2014-11-24 18:23:46 +0000
@@ -41,14 +41,20 @@
     update = delete = None
 
     def read(self, request, system_id):
-        """Read all MAC addresses related to a Node."""
+        """Read all MAC addresses related to a Node.
+
+        Returns 404 if the node is not found.
+        """
         node = Node.objects.get_node_or_404(
             user=request.user, system_id=system_id, perm=NODE_PERMISSION.VIEW)
 
         return MACAddress.objects.filter(node=node).order_by('id')
 
     def create(self, request, system_id):
-        """Create a MAC address for a specified Node."""
+        """Create a MAC address for a specified Node.
+
+        Returns 404 if the node is not found.
+        """
         node = Node.objects.get_node_or_404(
             user=request.user, system_id=system_id, perm=NODE_PERMISSION.EDIT)
         mac = node.add_mac_address(request.data.get('mac_address', None))
@@ -71,7 +77,10 @@
     model = MACAddress
 
     def read(self, request, system_id, mac_address):
-        """Read a MAC address related to a Node."""
+        """Read a MAC address related to a Node.
+
+        Returns 404 if the node or the MAC address is not found.
+        """
         node = Node.objects.get_node_or_404(
             user=request.user, system_id=system_id, perm=NODE_PERMISSION.VIEW)
 
@@ -80,7 +89,11 @@
             MACAddress, node=node, mac_address=mac_address)
 
     def delete(self, request, system_id, mac_address):
-        """Delete a specific MAC address for the specified Node."""
+        """Delete a specific MAC address for the specified Node.
+
+        Returns 404 if the node or the MAC address is not found.
+        Returns 204 after the MAC address is successfully deleted.
+        """
         validate_mac(mac_address)
         node = Node.objects.get_node_or_404(
             user=request.user, system_id=system_id, perm=NODE_PERMISSION.EDIT)
 
=== modified file 'src/maasserver/api/nodes.py'
--- src/maasserver/api/nodes.py	2014-11-05 15:10:12 +0000
+++ src/maasserver/api/nodes.py	2014-11-24 18:23:46 +0000
@@ -197,7 +197,10 @@
         return node.owner.username
 
     def read(self, request, system_id):
-        """Read a specific Node."""
+        """Read a specific Node.
+
+        Returns 404 if the node is not found.
+        """
         return Node.objects.get_node_or_404(
             system_id=system_id, user=request.user, perm=NODE_PERMISSION.VIEW)
 
@@ -231,6 +234,9 @@
         :type power_parameters_skip_check: unicode
         :param zone: Name of a valid physical zone in which to place this node
         :type zone: unicode
+
+        Returns 404 if the node is node found.
+        Returns 403 if the user does not have permission to update the node.
         """
         node = Node.objects.get_node_or_404(
             system_id=system_id, user=request.user, perm=NODE_PERMISSION.EDIT)
@@ -243,7 +249,12 @@
             raise ValidationError(form.errors)
 
     def delete(self, request, system_id):
-        """Delete a specific Node."""
+        """Delete a specific Node.
+
+        Returns 404 if the node is not found.
+        Returns 403 if the user does not have permission to delete the node.
+        Returns 204 if the node is successfully deleted.
+        """
         node = Node.objects.get_node_or_404(
             system_id=system_id, user=request.user,
             perm=NODE_PERMISSION.ADMIN)
@@ -274,6 +285,9 @@
             gracefully before powering off, while a hard power off
             occurs immediately without any warning to the OS.
         :type stop_mode: unicode
+
+        Returns 404 if the node is not found.
+        Returns 403 if the user does not have permission to stop the node.
         """
         stop_mode = request.POST.get('stop_mode', 'hard')
         node = Node.objects.get_node_or_404(
@@ -300,6 +314,12 @@
         deal with the encapsulation of binary data, but couldn't make it work
         with the framework in reasonable time so went for a dumb, manual
         encoding instead.
+
+        Returns 404 if the node is not found.
+        Returns 403 if the user does not have permission to stop the node.
+        Returns 503 if the start-up attempted to allocate an IP address,
+        and there were no IP addresses available on the relevant cluster
+        interface.
         """
         user_data = request.POST.get('user_data', None)
         series = request.POST.get('distro_series', None)
@@ -335,7 +355,12 @@
 
     @operation(idempotent=False)
     def release(self, request, system_id):
-        """Release a node.  Opposite of `NodesHandler.acquire`."""
+        """Release a node.  Opposite of `NodesHandler.acquire`.
+
+        Returns 404 if the node is not found.
+        Returns 403 if the user does not have permission to release the node.
+        Returns 409 if the node is in a state where it may not be released.
+        """
         node = Node.objects.get_node_or_404(
             system_id=system_id, user=request.user, perm=NODE_PERMISSION.EDIT)
         if node.status == NODE_STATUS.READY:
@@ -360,6 +385,8 @@
         already in the 'ready' state this is considered a re-commissioning
         process which is useful if commissioning tests were changed after
         it previously commissioned.
+
+        Returns 404 if the node is not found.
         """
         node = get_object_or_404(Node, system_id=system_id)
         form_class = get_action_form(user=request.user)
@@ -383,6 +410,8 @@
         Note that this is returned as BSON and not JSON. This is for
         efficiency, but mainly because JSON can't do binary content
         without applying additional encoding like base-64.
+
+        Returns 404 if the node is not found.
         """
         node = get_object_or_404(Node, system_id=system_id)
         probe_details = get_single_probed_details(node.system_id)
@@ -415,6 +444,12 @@
         an admin to give a node a stable IP, since normally an automatic
         IP is allocated to a node only during the time a user has
         acquired and started a node.
+
+        Returns 404 if the node is not found.
+        Returns 409 if the node is in an allocated state.
+        Returns 400 if the mac_address is not found on the node.
+        Returns 503 if there are not enough IPs left on the cluster interface
+        to which the mac_address is linked.
         """
         node = get_object_or_404(Node, system_id=system_id)
         if node.status == NODE_STATUS.ALLOCATED:
@@ -449,6 +484,10 @@
         :param error_description: An optional description of the reason the
             node is being marked broken.
         :type error_description: unicode
+
+        Returns 404 if the node is not found.
+        Returns 403 if the user does not have permission to mark the node
+        broken.
         """
         node = Node.objects.get_node_or_404(
             user=request.user, system_id=system_id, perm=NODE_PERMISSION.EDIT)
@@ -459,7 +498,12 @@
 
     @operation(idempotent=False)
     def mark_fixed(self, request, system_id):
-        """Mark a broken node as fixed and set its status as 'ready'."""
+        """Mark a broken node as fixed and set its status as 'ready'.
+
+        Returns 404 if the node is not found.
+        Returns 403 if the user does not have permission to mark the node
+        broken.
+        """
         node = Node.objects.get_node_or_404(
             user=request.user, system_id=system_id, perm=NODE_PERMISSION.ADMIN)
         node.mark_fixed()
@@ -473,11 +517,14 @@
     def power_parameters(self, request, system_id):
         """Obtain power parameters.
 
-        This method is reserved for admin users.
+        This method is reserved for admin users and returns a 403 if the
+        user is not one.
 
         This returns the power parameters, if any, configured for a
         node. For some types of power control this will include private
         information such as passwords and secret keys.
+
+        Returns 404 if the node is not found.
         """
         node = get_object_or_404(Node, system_id=system_id)
         return node.power_parameters
@@ -492,12 +539,13 @@
         Use this method sparingly as it ties up an appserver thread
         while waiting.
 
-        If there is a problem, SERVICE_UNAVAILABLE is returned with text
-        explaining why.
-
         :param system_id: The node to query.
         :return: a dict whose key is "state" with a value of one of
             'on' or 'off'.
+
+        Returns 404 if the node is not found.
+        Returns 503 (with explanatory text) if the power state could not
+        be queried.
         """
         node = get_object_or_404(Node, system_id=system_id)
         ng = node.nodegroup
@@ -540,6 +588,10 @@
         """Abort a node's current operation.
 
         This currently only supports aborting of the 'Disk Erasing' operation.
+
+        Returns 404 if the node could not be found.
+        Returns 403 if the user does not have permission to abort the
+        current operation.
         """
         node = Node.objects.get_node_or_404(
             system_id=system_id, user=request.user,
@@ -648,6 +700,8 @@
         :type mac_address: unicode
         :return: 'true' or 'false'.
         :rtype: unicode
+
+        Returns 400 if any mandatory parameters are missing.
         """
         mac_address = get_mandatory_param(request.GET, 'mac_address')
         mac_addresses = MACAddress.objects.filter(mac_address=mac_address)
@@ -656,7 +710,10 @@
 
     @operation(idempotent=False)
     def accept(self, request):
-        """Accept a node's enlistment: not allowed to anonymous users."""
+        """Accept a node's enlistment: not allowed to anonymous users.
+
+        Always returns 401.
+        """
         raise Unauthorized("You must be logged in to accept nodes.")
 
     @classmethod
@@ -726,6 +783,9 @@
         :return: The system_ids of any nodes that have their status changed
             by this call.  Thus, nodes that were already accepted are
             excluded from the result.
+
+        Returns 400 if any of the nodes do not exist.
+        Returns 403 if the user is not an admin.
         """
         system_ids = set(request.POST.getlist('nodes'))
         # Check the existence of these nodes first.
@@ -813,6 +873,12 @@
         :return: The system_ids of any nodes that have their status
             changed by this call. Thus, nodes that were already released
             are excluded from the result.
+
+        Returns 400 if any of the nodes cannot be found.
+        Returns 403 if the user does not have permission to release any of
+        the nodes.
+        Returns a 409 if any of the nodes could not be released due to their
+        current state.
         """
         system_ids = set(request.POST.getlist('nodes'))
          # Check the existence of these nodes first.
@@ -964,6 +1030,9 @@
         :param agent_name: An optional agent name to attach to the
             acquired node.
         :type agent_name: unicode
+
+        Returns 409 if a suitable node matching the constraints could not be
+        found.
         """
         form = AcquireNodeForm(data=request.data)
         maaslog.info(
@@ -1006,6 +1075,8 @@
             will be taken out of their physical zones.
         :param nodes: system_ids of the nodes whose zones are to be set.
            (An empty list is acceptable).
+
+        Raises 403 if the user is not an admin.
         """
         data = {
             'action': 'set_zone',
@@ -1027,6 +1098,8 @@
         :type id: iterable
 
         :return: A dictionary of power parameters, keyed by node system_id.
+
+        Raises 403 if the user is not an admin.
         """
         match_ids = get_optional_list(request.GET, 'id')
 
@@ -1043,6 +1116,9 @@
 
         :param nodes: Mandatory list of system IDs for nodes whose status
             you wish to check.
+
+        Returns 400 if mandatory parameters are missing.
+        Returns 403 if the user has no permission to view any of the nodes.
         """
         system_ids = set(request.GET.getlist('nodes'))
         # Check the existence of these nodes first.
 
=== modified file 'src/maasserver/api/ssh_keys.py'
--- src/maasserver/api/ssh_keys.py	2014-08-16 15:05:54 +0000
+++ src/maasserver/api/ssh_keys.py	2014-11-24 18:23:46 +0000
@@ -83,13 +83,20 @@
     create = update = None
 
     def read(self, request, keyid):
-        """GET an SSH key."""
+        """GET an SSH key.
+
+        Returns 404 if the key does not exist.
+        """
         key = get_object_or_404(SSHKey, id=keyid)
         return key
 
     @operation(idempotent=False)
     def delete(self, request, keyid):
-        """DELETE an SSH key."""
+        """DELETE an SSH key.
+
+        Returns 404 if the key does not exist.
+        Returns 401 if the key does not belong to the calling user.
+        """
         key = get_object_or_404(SSHKey, id=keyid)
         if key.user != request.user:
             return HttpResponse(
 
=== modified file 'src/maasserver/api/ssl_keys.py'
--- src/maasserver/api/ssl_keys.py	2014-08-17 01:01:12 +0000
+++ src/maasserver/api/ssl_keys.py	2014-11-24 18:23:46 +0000
@@ -83,7 +83,11 @@
     create = update = None
 
     def read(self, request, keyid):
-        """GET an SSL key."""
+        """GET an SSL key.
+
+        Returns 404 if the keyid is not found.
+        Returns 401 if the key does not belong to the requesting user.
+        """
         key = get_object_or_404(SSLKey, id=keyid)
         if key.user != request.user:
             return HttpResponse(
@@ -92,7 +96,11 @@
 
     @operation(idempotent=True)
     def delete(self, request, keyid):
-        """DELETE an SSL key."""
+        """DELETE an SSL key.
+
+        Returns 401 if the key does not belong to the requesting user.
+        Returns 204 if the key is successfully deleted.
+        """
         key = get_object_or_404(SSLKey, id=keyid)
         if key.user != request.user:
             return HttpResponse(
 
=== modified file 'src/maasserver/api/tags.py'
--- src/maasserver/api/tags.py	2014-08-18 11:43:18 +0000
+++ src/maasserver/api/tags.py	2014-11-24 18:23:46 +0000
@@ -62,7 +62,10 @@
         )
 
     def read(self, request, name):
-        """Read a specific Tag"""
+        """Read a specific Tag.
+
+        Returns 404 if the tag is not found.
+        """
         return Tag.objects.get_tag_or_404(name=name, user=request.user)
 
     def update(self, request, name):
@@ -74,6 +77,8 @@
             It is meant as a human readable description of the tag.
         :param definition: An XPATH query that will be evaluated against the
             hardware_details stored for all nodes (output of `lshw -xml`).
+
+        Returns 404 if the tag is not found.
         """
         tag = Tag.objects.get_tag_or_404(
             name=name, user=request.user, to_edit=True)
@@ -90,7 +95,11 @@
             raise ValidationError(form.errors)
 
     def delete(self, request, name):
-        """Delete a specific Tag."""
+        """Delete a specific Tag.
+
+        Returns 404 if the tag is not found.
+        Returns 204 if the tag is successfully deleted.
+        """
         tag = Tag.objects.get_tag_or_404(
             name=name, user=request.user, to_edit=True)
         tag.delete()
@@ -98,7 +107,10 @@
 
     @operation(idempotent=True)
     def nodes(self, request, name):
-        """Get the list of nodes that have this tag."""
+        """Get the list of nodes that have this tag.
+
+        Returns 404 if the tag is not found.
+        """
         tag = Tag.objects.get_tag_or_404(name=name, user=request.user)
         return Node.objects.get_nodes(
             request.user, NODE_PERMISSION.VIEW, from_nodes=tag.node_set.all())
@@ -120,6 +132,8 @@
         This is considered a maintenance operation, which should normally not
         be necessary. Adding nodes or updating a tag's definition should
         automatically trigger the appropriate changes.
+
+        Returns 404 if the tag is not found.
         """
         tag = Tag.objects.get_tag_or_404(name=name, user=request.user,
                                          to_edit=True)
@@ -141,6 +155,10 @@
             supplied, then the requester must be the worker associated with
             that nodegroup, and only nodes that are part of that nodegroup can
             be updated.
+
+        Returns 404 if the tag is not found.
+        Returns 401 if the user does not have permission to update the nodes.
+        Returns 409 if 'definition' doesn't match the current definition.
         """
         tag = Tag.objects.get_tag_or_404(name=name, user=request.user)
         nodegroup = None
@@ -196,6 +214,8 @@
             value overrides the global 'kernel_opts' setting. If more than one
             tag is associated with a node, the one with the lowest alphabetical
             name will be picked (eg 01-my-tag will be taken over 99-tag-name).
+
+        Returns 401 if the user is not an admin.
         """
         if not request.user.is_superuser:
             raise PermissionDenied()
 
=== modified file 'src/maasserver/api/users.py'
--- src/maasserver/api/users.py	2014-08-16 15:14:46 +0000
+++ src/maasserver/api/users.py	2014-11-24 18:23:46 +0000
@@ -59,6 +59,8 @@
         :type password: unicode
         :param is_superuser: Whether the new user is to be an administrator.
         :type is_superuser: bool ('0' for False, '1' for True)
+
+        Returns 400 if any mandatory parameters are missing.
         """
         username = get_mandatory_param(request.data, 'username')
         email = get_mandatory_param(request.data, 'email')
 
=== modified file 'src/maasserver/api/zones.py'
--- src/maasserver/api/zones.py	2014-08-16 14:54:27 +0000
+++ src/maasserver/api/zones.py	2014-11-24 18:23:46 +0000
@@ -48,12 +48,18 @@
     create = None
 
     def read(self, request, name):
-        """GET request.  Return zone."""
+        """GET request.  Return zone.
+
+        Returns 404 if the zone is not found.
+        """
         return get_object_or_404(Zone, name=name)
 
     @admin_method
     def update(self, request, name):
-        """PUT request.  Update zone."""
+        """PUT request.  Update zone.
+
+        Returns 404 if the zone is not found.
+        """
         zone = get_object_or_404(Zone, name=name)
         form = ZoneForm(instance=zone, data=request.data)
         if not form.is_valid():
@@ -62,7 +68,11 @@
 
     @admin_method
     def delete(self, request, name):
-        """DELETE request.  Delete zone."""
+        """DELETE request.  Delete zone.
+
+        Returns 404 if the zone is not found.
+        Returns 204 if the zone is successfully deleted.
+        """
         zone = get_one(Zone.objects.filter(name=name))
         if zone is not None:
             zone.delete()