Rest - Boolean Parameters Naming Conventions
What Are the Standards for Boolean Parameters in Rest Which Indicates Whether or Not Certain Parts of the Response Should Be Included. Should They Be Prefixed...
What are the standards for boolean parameters in REST which indicates whether or not certain parts of the response should be included. Should they be prefixed with "include" "with" or similar prefix?
Example:
Say, I have a REST service GET /buildings which returns buildings:
[
{
name: "The Empire State Building",
flors: 102
}
]
Now when there is a use case to include the address, but the address is not always needed (because let's say getting address is quite expensive in the backend, so it is better not to include that by default).
I would like to add parameter which instructs the backend to include address in response, say:
GET /buildings?address=true:
[
{
"name": "The Empire State Building",
"flors": 102,
"address": {
"street" : "Fifth Avenue",
"number": 99
}
}
]
Now the question is how this address parameter should be named: "includeAddress=true", "address=true"or what should be the name?
2 Answers
Now the question is how this address parameter should be named: "includeAddress=true", "address=true"or what should be the name?
REST doesn't care what spelling you use for your identifiers, outside of the spelling restrictions placed on URI (for example, reserved characters)
From the point of view of generic HTTP components, /buildings and /buildings?address=true are two different, unrelated, resources.
So the choice of includeAddress vs address vs 3e8f8e8b-149a-430f-9c9d-e13c570ff8e4 is really left to your local naming conventions. The machines don't care, but humans take some comfort from consistency, familiarity, and so on.
Think of them like variable names in your code - the compiler/interpreter doesn't care, so long as your spellings respect the language syntax. But your colleagues will expect the spellings to confirm to the local style guide.
GET /buildings?address=true sounds like a query that filters for buildings that have addresses. But that is not what you want to say.
I'd use matrix parameters like this:
# Include the address information
GET /buildings;include=address
# Include the address and insurance information
GET /buildings;include=address,insurance
Alexander Ross has covered the video game industry for a decade, writing deep dives on game design, esports tournaments, VR developments, and gaming culture.
