An environment alias allows you to access and modify the data of an environment, called the target environment, through a different static identifier.
Currently, only one alias with the ID master is provided, and it cannot be renamed or deleted.
Aliases and target environments can be used to enhance your development and deployment workflows. For example, you can safely apply content model changes and roll them back when necessary or use them in your CI/CD pipelines.
Requesting environment entities through aliases
You can request entities like assets, entries and locales through the environment alias (i.e. master), by using the alias ID in place of the environment ID.
For example, to get all entries from an aliased environment called release-1, use
/spaces/<space-id>/environments/master/entries. This will implicitly request content from the release-1 environment.
spaces/<space-id>/entries without the environment alias fragment will have the same outcome.
For other operations through an environment alias, the same URL with and/or without the fragment can be used.
Common uses for environment aliases
Enabling risk-free releases and instant rollbacks
Your master alias should be used to serve your “production” content. Use it to reference your most up-to-date, currently-used environment. All your apps can access this content by either specifically referencing
/spaces/<space_id>/environments/master/content_types/... or leaving out the environment fragment alltogether: /
Aliases empower you to quickly switch which environment is being served from these routes. Simply send a PUT request to re-target the master alias to a different environment. If something goes wrong and you need to roll it back, simply re-target master to any previous environment.
Environment alias aware resources
All Environment aware resources can be interacted with through environment aliases.
Environment aliases and webhooks
Webhooks can be triggered for an environment alias using the
filters property of a
webhook just like environments. Webhooks only trigger for a given environment alias if it is used via that alias. Example: for a webhook set to trigger on the
master environment alias only
PUT spaces/<space-id>/environments/entries/my-blog-postwould trigger the webhook
PUT spaces/<space-id>/environments/master/entries/my-blog-postwould trigger the webhook
PUT spaces/<space-id>/environments/environment-to-serve/entries/my-blog-postwould not trigger the webhook
Please refer to the webhooks reference for more details.
Environment aliases and API keys
You can select both environments and environment aliases that your API key will give you access to. Your API key configuration remains unchanged when you set up aliases in your space to use environment aliases.
It is recommended for editors to always work on the master alias.