Naming boolean parameters in your API

Developers love boolean parameters 😅.

You may use names such as is_enabled, is_active, is_published, and many other variants in your API endpoints.

It usually aims to filter data or toggle some behaviors.

2 states

Because its value is either true or false, a boolean parameter usually represents two different states in API requests and responses.

If the API endpoint lists some items, and you use the is_published parameter set to true, you'll only get "published" posts:

https://myapi.com/v1/posts?is_published=true

Reciprocally, if you set the value to false, you'll probably get drafts, and other statuses:

https://myapi.com/v1/posts?is_published=false

N.B.: by convention, such endpoint would only list published posts by default.

🙏 Bad practices to avoid

Don't be too long

You must be extra vigilant with names. The name should be self-explanatory and short.

For example:

❌ Don't use has_been_registered_and_activated

✅ Use is_activated instead

Don't make it too short

While concise names are recommended, you must avoid acronyms and abbreviations.

Single letter names are not readable.

🐬 Never use negative states

disabled, is_disabled, is_not_active, or has_no_id will likely create confusion for both API consumers and maintainers.

❌ Double negatives kill dolphins:

if (!$account->is_not_activated)

✅ Use more intuitive flags:

if ($account->is_activated)

Choose your prefix wisely

Don't use is_allowed_to_, as can_ is the standard for such usage.

By convention:

• use is_ for states or conditions
• use can_ for capabilities or permissions

Don't use different names for the same purpose

It's not uncommon two different endpoints require the same parameter name to represent a specific state.

Let's say you have is_enabled on some endpoint.

The API should not use variants in other endpoints, like enabled or is_on.

Consistency is the key.

Don't mix styles

Mixing camel case with snake case (or any other "custom" style) makes your naming convention inconsistent.

Stick to one style for the whole codebase.

Don't add too many boolean parameters

You may find the perfect name for your parameter.

However, too many boolean parameters will harm readability.

Too many states can lead to conflicts and logic errors, with parameters that override each other.

Don't use debug parameters

❌ It's not uncommon to find hidden parameters like debug or is_debug in some APIs:

https://myapi.com/v2/posts?debug=true

In this case, you get the debugging infos.

Not only that it extends the attack surface for hackers, but you may also crash your own endpoint trying to load too much data.

✅ Instead, try to reproduce the bug on your local installation or a dedicated environment.

Maybe don't use boolean parameters...

As usual, it's all about the context.

However, many boolean parameters are actually lists.

It's just that, for now, you only have two cases. Boolean parameters are not extensible.

❌ Don't turn an existing boolean parameter into a list. That would be a breaking change.

❌ While incrementing a new version may seem a better choice (e.g., /v2/myendpoint?my_param=iAmNoLongerBoolean), it may be still confusing for your API consumers, and you would have to maintain two versions.

✅ Instead, use enumerations or other types to represent your data more accurately.

😈 The hell of nullable booleans

❌ Nullable booleans can represent 3 states:

• true
• false
• null

Think twice before implementing that, as users might be confused with what the null value really means.

It can complicate logic significantly and will likely require extensive documentation.

✅ Again, enumerations might be a better choice in your case.

✅ Another approach would consist of using default values (e.g., false).

Wrap up

Naming is hard, especially when it comes to boolean parameters.

Keep it simple and follow standards whenever you can.