To identify specific objects in the environment, the API uses references to point to those objects.Internally, the API uses references by internal ID to point to other objects. When you're adding or modifying objects using the API, you can also reference the objects by their codenames or external IDs, if present.When specifying references to objects, the object can be identified by one of three properties:
Internal ID such as 18b43cc5-f4fd-0172-842b-3ae2c878cf6f
Generated by the system automatically.
Unique per object type, such as content item, content type, and more.
Unique per object type, such as content item, content type, and more.
Can be used to specify most objects.
External ID such as custom-object-identifier
Specified manually when creating the object through the Management API. The external ID cannot be changed later.
Unique per object type. For example, the uniqueness applies to content types and their elements within an environment, content items within an environment, and so on. This means you can have a content type and an element with the same external ID, but no two elements can use the same external ID within an environment.
Can be used to specify custom identifiers for user-created objects such as assets, content items, content types, and more.
By using external IDs to reference other objects, you can import your content in the order you prefer.For example, when importing multiple articles that contain images, you can reference these images with external IDs, such as roaster or coffee-cup, before uploading them. The referenced images will be visible in the UI only after you add them as assets via the API. With this approach, you can choose whether you want to create content items first and then upload binary files for assets, or vice versa.This means you can use external IDs to reference objects that don't exist yet and add the objects via the API later. References to non-existent objects will be stored and retrieved via the API as internal IDs.To check for any references to not-yet-created objects, we recommend you validate your content.If you use external IDs to reference non-existent objects in your elements, the referenced objects won't be shown in the UI. This is because the system cannot find those objects. The referenced assets, content items, and taxonomy terms will be displayed after you create them with their specific external IDs via the Management API.To add the missing objects, see:
Reference to a specific object in the environment.
When editing codenames, the new codenames must meet the following conditions:
Only lowercase letters, numbers, and underscores are permitted.
Codenames must start with a letter or an underscore and have at least one character.
Codenames are usually limited to 60 characters, but longer codenames are allowed for multiple choice options and taxonomy terms.
Codenames of elements within a snippet must be prefixed with the snippet's codename.
Codenames must be unique per object type. This applies to, for example, every element within a content type, every content type within an environment, every content item within an environment, and so on.
This means the following applies when codenames are generated automatically:
All letters are made lowercase.
All forbidden characters are replaced by _.
For any names that start with a number, the codename will start with n.
Codenames that duplicate another codename will have a random string attached to the end.
Codenames of elements within a snippet will be prefixed with the snippet's codename.
