Renato Oliveira
 - 
April 7, 2022

Why API names matter, and why you should name them appropriately

"API name", "Unique name" or "developer name". Sounds familiar? They usually refer to the same thing: a unique piece of string that refers to a piece of metadata in a Salesforce org. You might not be too familiar with it, but every time you create a new custom object, field, record type, approval process, workflow rule, email alert or picklist value you name things in a programmatic way too (most of those - and many others - have also the "label" field, that is what your users see when interacting with those items). The problem is when you do this too quickly and forget to give the API name a proper name.

Gotta go fast and create those values quickly!

If you have developed some solution with code in the platform, or even with a little more advanced flows, you have probably worked with those names before. They show up all the time in code and flows. In fact, within the underlying metadata in your org all that matters for Salesforce is the API name. In Apex only the API name is ever used, too.

So why does the API name matter?

it is how an administrator names things that the platform glues together to make an application run. API names are part of the fundamental building blocks that allow the platform to be so flexible. API names are  ultimately part of the user interface and experience, and the  administrator is responsible  to build and maintain these in a  Salesforce org. Does that convince you? If not, then check the use case below.

"I want users to be able to select a value from a dropdown in a page, but they are not users on the system. These values correspond to lines that represent an option in a contract that will be created when they submit the information to us through this page."
What's up with that? No users on the system means that the page is public. So it is exposed on a site. So the guest user is editing the record. OK so far. But then what about that dropdown? Because of how other application components work this cannot be a reference to an object either. It needs to be a picklist. The text of one of those values reads like this:
"A (IIV) for these purposes, the party agrees that the funds received, directly or indirectly, following an offer or invitation to the site (within the meaning of section 8) under the terms of the master agreement provided before, are to be invested."

And it looks like this in the picklist value list:

And in the Flow Builder experience it looks like this (ignore the fact that the picklist is called "Status"):

Notice that this piece of text has 250 characters. It is well within the limit of characters that Salesforce allows us to use for a picklist value. It is not pretty in the UI, for sure, but it is a requirement for now. When creating this picklist value in Setup Salesforce will create the API name automatically for you with a copy of the label. That's usually how it goes for small values.

Now imagine this 250-character is used in Apex:

The developer working on this might decide to use a global variable in Apex just so it is defined once, possibly adding tech-debt to the org's code: 

Or they might assign the value directly wherever it is required. The code will occupy an entire editor's line if assigned directly. Worst case scenario: they might type it by hand and miss a letter or copy and paste it in parts, missing a character too. Anyway, the idea here is that a big API name is much more error-prone than a simpler and smaller value.

"But how can this prevent a deployment?"

... you might be asking. It can and probably will if you not only use a huge text like that, but also if such text contains special characters like parenthesis. Let me explain: when you create a change set or make a deployment using a third-party tool like Gearset, Salesforce exports the metadata definition of your field and its picklist values to a XML file.

When this happens the special characters are HTML-encoded, meaning that the opening and closing parenthesis are replaced with "%28" and "%29" respectively, which are now three characters each. So what happens if you have two groups of parenthesis in your API name? Exactly: now they are not 4 characters, but 12. At 258 characters your picklist API name exceeded the limit and can no longer be deployed.

At this point the Salesforce API will return "Picklist value is too long for the max size of 255" to you.

And yes: this happens only for the API name, because that is the name that is actually saved in the database. Labels are stored elsewhere, for performance reasons. So when you view a record in your browser, the platform does its magic in both Classic and Lightning experiences and first fetches the record from the database with all fields with their "raw" API values.

Then it goes through another procedure where those are mapped to their labels so they can show up in the UI.

This can be easily solved by using - like mentioned before - simpler and shorter API names. Like "OPTION_A", for instance. The same principle applies to everything you create in Salesforce that has a "Developer Name" field. Look at how it is much more readable:

"But Salesforce should fix this, not us!" you might be thinking. But Salesforce themselves already stated in a Known Issue that they won't fix it. So maybe go a bit slower when creating new things in the org, and think more carefully about how they should be named? That might save you a few hours of debugging, code formatting and of course: deployment errors.

Renato Oliveira

Salesforce Developer
Salesforce Partner EMPAUA

Renato Oliveira

We create solutions that drive your business success.
Salesforce Partner EMPAUA

Do you need Salesforce support?

Request a Consultation and let our experts advise you.

Want to join the team?

Take a look at our job openings and be part of our mission.

Related posts

Ready to start your digital transformation?