I'm writing a new API that takes a boolean parameter "damaging" to flag whether or not a revision is judged to be damaging, and learned something important about the MediaWiki API:
Boolean parameters work like HTML checkboxes: if the parameter is specified in the HTTP request, regardless of value, it is considered true. For a false value, omit the parameter entirely. The best way to specify a true parameter in an HTTP request is to use someParam=; the trailing = ensures the browser or HTTP library does not discard the "empty" someParam.
This might make sense for APIs which will be driven directly by an HTML form, but I don't think it's a good idea in any other context. I see the checkbox-style parameter passing as problematic for these reasons:
- No ability to require the parameter, since passing "false" can only be done by omitting the parameter.
- Passing an empty value for true has bad semantics, and is unclear to the uninitiated.
- Omitting the parameter has bad semantics, because it's unclear that we're actually setting something to false.
Obviously we can't do anything to change such a deep assumption in the existing API, but my suggestion is that we introduce a new data type "strict-boolean", which behaves like the other data types, so for a required parameter, we have:
- "damaging=true" is parsed as true.
- "damaging=false" is parsed as false.
- "damaging=", "damaging=0", or any other value results in an error.
- Omitting the "damaging" parameter results in an error.