apidoc doesn't show the possible fields to use with order_by in searchTasks

[Ursula Junque]

It's not clear which fields should be used with the order_by parameter in the searchTasks method. API docs only say that order_by is a list of fields. Trying to run searchTasks ordering by date_created, that's the name of the property in a bug_task, you'll run into this:

  KeyError: u'date_created'

as can be seen in OOPS-1507EA75, OOPS-1507EB64 and OOPS-1507EA77.

So, it would nice to have a list of fields that can be used in the docs, so we wouldn't have to guess or grep the code to find it out. In that case, the name of the field is 'datecreated'.

[Markus Korn (thekorn)]

This is actually something which bothers me for a while now, but I was too lazy to report it.
I think there are at least two issues hidden in this bugreport:
 1.) handling of invalid values in launchpad
 2.) documentation of valid values

In my opinion invalid values should never raise an OOPS, instead they should result in a 'Bad request' response. This response should then contain some information about what went wrong, and a list of valid values. This behaviour is for example implemented for the 'status' argument of searchTasks:

In [4]: zg.searchTasks (status="dfg")
[.....]
HTTPError: HTTP Error 400: Bad Request
---------------------------------------------------------------------------
Response: {'connection': 'close',
 'content-length': '208',
 'content-type': 'text/plain',
 'date': 'Thu, 18 Feb 2010 11:41:39 GMT',
 'server': 'zope.server.http (HTTP)',
 'status': '400',
 'vary': 'Cookie,Authorization,Accept',
 'via': '1.1 wildcard.edge.launchpad.net',
 'x-powered-by': 'Zope (www.zope.org), Python (www.python.org)'}
Content: 'status: Invalid value "dfg". Acceptable values are: New, Incomplete (with response), Incomplete (without response), Incomplete, Invalid, Won\'t Fix, Confirmed, Triaged, In Progress, Fix Committed, Fix Released'
---------------------------------------------------------------------------

The same situation is handled in a completly different way for the 'hardware_bus' parameter, it does the check on client side and raises a ValueError:

In [5]: zg.searchTasks (hardware_bus="dfg")
---------------------------------------------------------------------------
ValueError Traceback (most recent call last)
[....]
ValueError: Invalid value 'dfg' for parameter 'hardware_bus': valid values are: "System", "PCI", "USB", "IEEE1394", "SCSI", "Parallel Port", "Serial port", "IDE", "ATA", "Floppy", "IPI", "SATA", "SAS", "PC Card (32 bit)", "PCMCIA (16 bit)"

The good thing about this client side approach is that the valid values are automatically documented in +apidoc

IMO the best fix for this bug would be to do a combination of both, do as much client side checks as possible, but return a verbose HTTP error response incase a invalid value finds its way to the server.

The other part of the bugreport is documentation, currently only DBEnumeratedType values are listed in the docs, I think also fields of type 'Choice' and 'List of Choice' should be documented in the same way.

[Eleanor Berger (intellectronica)]

To fix this bug the order_by argument needs to start taking a value from an enumeration, rather than a string. There's an existing bug for that, so I marked this one as a duplicate.