Question

Consider an automated build system that stores results in a database and offers tabular display of results via dynamic html in response to http GET requests. Lots of different users want to see different subsets of the results, so there are parsing scripts in PHP each of which accepts multiple optional filtering parameters and values. For example, (I’m leaving off the http part so nobody here actually clicks this example URL):

display_results.php?componenent_name=my_comp1&build_type=build_type1&build_owner=fred

Even if the list of all possible parameters and their permitted values are listed on some help page, when the user is creating a request URL, s/he may not have that documentation at hand. Instead, depends on memorizing the valid parameters (including their spelling) and the allowed values. Sometimes s/he will get that wrong.

Question

From the point of view of end-user usability as well as developer maintainability, which of the following options is best in response to such user errors:

1. Ignore invalid parameters or values
2. Ignore invalid parameters, return nothing for invalid values
3. Return as much valid table data as possible plus an error message (with correct usage)
4. Return just an error message (with correct usage)
5. Make best attempt at auto-correction
6. Other (explain)

For example, if the database contains data for build_type1 and fred and joe for three components called comp1, comp2, and comp3, and user (erroneously) writes:

display_results.php?name=comp1,comp2&build_type=build_type1&build_owner=john

1. Would return all results (because ignored wrong parameter name “name”, invalid value “john”)
2. Would return nothing because no data for john
3. Would return all results for build_type1 plus messages “no build_owner = john” and “maybe you meant ‘component_name'”
4. Would return just messages “no build_owner = john” and “maybe you meant ‘component_name'”
5. Would return comp1 and comp2 results for build_type1 for joe
6. Other (describe)

I’m defining usability as consistency with widely-used, well-behaved web apps that are out there — if users are happy with those they would be happy with the app I’m describing too.

I am asking this question because I am a key user of such scripts, make a good number of enhancement requests, and want to get some backing for further requests.

===
About the interface — free-form or “builder page”. Yes, I am talking about free-form. There is a “builder page” in the system but (a) it never offers all the options that all users seem to want and (b) I have not been able to push through a “create permalink” enhancement request.

===
Thanks for chosen answer — not enough space in comment:

Thanks @pygorex1! You gave an answer that puts my question in the context of a well-known software construct — the API. And gave a good (if perhaps exaggerated 😉 ) example of the impact of violating these principles. Finally, something had been bothering me about these scripts’ APIs, and when you mentioned “self-documenting”, you connected it up for me. What was bothering me was that when there’s little documentation (because it’s costly to keep up to date) and with partial results returned on user error (mine!), I don’t learn anything about the system. “Self-documenting” is probably the most succinct justification for the error-handling design you’ve recommended. Easier sell to users and maintainers!

Answer 1

This sounds remarkably like an API. One of the hallmarks of a good API is a having a clear and consistent syntax so users can get predictable results. Violating the syntax should result in a error.

Returning partial results even though the syntax is incorrect is a terrible design: when a user isn’t clearly stating what data they want there’s a good chance the data returned won’t be useful or will be discarded. Even worse, the data may be treated as being in a valid context even when it’s not.

An example. The system is designed to ignore invalid parameters. A client sends a comoponent_name parameter (a misspelling of component_name) requesting all components of type ‘A’. Subsequently, the system returns components of all types (‘A’, ‘B’, ‘C’ … ‘Z’). The client treats these results as all being of type ‘A’ and bases internal calculations and business logic on these results. Chaos ensues, as management bases their business decisions largely on this internal data analysis, the client jumps head-first into the wrong market segment and goes bankrupt.

Now, this is a doomsday scenario, but it illustrates a point: you can mitigate and even prevent systemic bugs by clearly defining your inputs and outputs.

Before returning any data, verify input parameters. When an invalid parameter is encountered return an error message explaining the correct syntax. This way, the system is self-documenting and will return predictable results.