How should REST API accept boolean values?
Whichever way you want it to, it's completely up to you as the architect/designer. true/false
is the most syntactically correct version, make sure that one works and add the other options as sugar if you want.
True and false
The true
and false
literals are just fine to represent boolean values. They are quite descriptive and, if your API supports JSON, true
and false
are definitively the obvious choices.
Enumerations
In a few situations, however, you may want to avoid boolean values because they cannot be expanded. You may want to consider enumerations instead.
It may be a poor comparison but it might help you to get the main idea of this approach: have a look at CSS properties such as overflow
or visibility
. They allow expandable values instead of only true
or false
. So new values can be easily added without changing the property names.
So, for the situation described in your question, to retrieve the default state of a resource, I would support a query parameter such as status
, that could have values such as default
and current
.
The following would return the default state of the resource:
GET /config?status=default HTTP/1.1
Host: example.com
Accept: application/json
And the following would return the current state of the resource:
GET /config?status=current HTTP/1.1
Host: example.com
Accept: application/json
If no query parameter is provided, you could that the client wants the current state of the resource.
If you need to restore the resource state to its default state, consider using PUT
, sending the new representation of the resource in the request payload. Something like:
PUT /config/status HTTP/1.1
Host: example.com
Content-Type: application/json
{
"value": "default"
}