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" 
}

Tags:

Http

Url

Rest