REST - boolean parameters naming conventions

Question

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?

Like described here, i think you should avoid camelcases: https://stackoverflow.com/questions/778203/are-there-any-naming-convention-guidelines-for-rest-apis I think address or as @BasilBattikhi said addressdetails is the way to go to have a clean call — G43beli, Mar 22 '18 at 09:40
@walkeros it's your API, it's really up to you. My 2 cents would be perhaps think about different endpoints for different data models e.g. `/buildings/full` / `/buildings/partial` (not saying those particular names but you get the idea). — James, Mar 22 '18 at 10:06

score 2 · Answer 1 · answered Mar 22 '18 at 10:39

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

score 2 · Accepted Answer · edited Oct 07 '21 at 10:55

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.

REST - boolean parameters naming conventions

2 Answers2