RFC-54 Introducing Space Alias in the Confluence URL

RFCs are a way for Atlassian to share what we’re working on with our valued developer community.

It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.

Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!

Summary of Project:

This new initiative will help address one of the most requested features in Confluence: allowing users to rename space keys. This will solve the problem of conflicting spaces during migrations.

  • Publish: June 7, 2024 (PST)
  • Discuss: June 20, 2024 (PST)
  • Resolve: June 28, 2024 (PST)

Problem:

The ability to change a Space key has garnered significant interest from numerous customers. Customers frequently request the capability to rename space keys due to organizational changes such as modifications in team or project names, acquisitions by other companies, organizational restructuring, or alterations in user names. Furthermore, it creates obstacles when attempting to migrate spaces between Confluence instances with identical space keys.

Proposed Solution:

Since the beginning, the Space key has been used as a unique and immutable field by our app developers. As part of the proposed solution, we are going to keep the existing Space key as it is.

What is being introduced is a Space Alias. This is can be created and applied to a Space after the creation of a Space. The Space Alias will be what is presented about a Space. So, in a URL where there was a Space key there will be a Space Alias. For example:

Existing URL: https://example.atlassian.net/wiki/spaces/SPACEKEY/settings/home

New Changed URL: https://example.atlassian.net/wiki/spaces/SPACEALIAS/settings/home

What is changing is that the field in the URL that is currently populated by the Space key will become a Space alias.

After a transition period, the provided Space key will be stored as a Space Alias and the Space Key will be an internally generated ID. No existing Space keys will be changed.

In addition, any stored URLs with a Space key or Space Alias will continue to work even if a new Space Alias is applied to a Space.

API Support:

All the APIs that are compatible with the space key will also be compatible with the space alias.

For instance, the Get Spaces (v2) API will accept an alias in the keys query parameters.

Key field in API Response

The key field in the API response will remain unchanged, consistently containing the actual space key (Internally generated id moving forward) for the specified space.

Existing Space Key

There will be no changes to the existing space keys. All current space keys will still utilize the UGC space key. Only spaces created after this launch will receive an internally generated ID.

No changes in AP.context.getContext()

The space key retrieved through the AP context remains unchanged. It will consistently return the actual space key in the response. The alias will be a new field that returns the new Space Alias. In the case where no Space Alias has been set, the Space Alias will be the same as the Space key.

AP.context.getContext()

{
    "confluence": {
        "space": {
            "key": "SPACEKEY",
            "id": "SPACEID",
            "alias": "SPACEALIAS" // New field coming as part of EAP
        },
        "content": {
            "plugin": "pluginKey",
            "type": "TYPE"
        }
    },
    "url": {
        "displayUrl": "https://example.atlassian.net/wiki"
    }
}

Supports URL redirect with older alias.

Links with previous space keys or aliases will be automatically redirected to the currently active alias. All APIs that require a space key will also support this functionality, ensuring that appropriate spaces are provided in response to older aliases.

The upcoming changes to the APIs as detailed below

  • V1 Create Space and Create Private Space APIs
    • The space key will now be an internally generated ID. We are going to deprecate the space key field in the above two APIs, and it will be marked as optional during the deprecation notice. During the deprecation period, if the space key is included in the request, the space will be created with the given space key.
    • A new field, alias, will be added. This will be used to create a space with the given alias. (This is an optional field during the deprecation period.)
    • The key field in the request is scheduled to be deprecated during the first week of January 2025. Following deprecation, the key provided in the create space request will be ignored.
  • V2 Get Spaces and Get Space By Id APIs
    • A new field, alias, will be added to the response.

Asks

We kindly request that the developer refrain from scanning URLs to parse space keys. If this is currently being done, we strongly recommend transitioning to AP.context.getContext() or utilizing our V2 Space API to obtain the correct space key from its response.

The Alias field is subject to change, so it is recommended to avoid using aliases to store your application data. Instead, opt for using the Space ID whenever feasible.

The initial release is scheduled for the end of June for developer EAP. This feature will be activated exclusively for developer sites, allowing you to test your apps against the change to ensure proper functionality. In the meantime, if your app is parsing the URL for space key, please make the necessary adjustments as outlined above.

If you are interested in registering your site for the developer EAP, Please follow the steps as described here

Thank you in advance for your collaboration and support in shaping the future of the Confluence

1 Like

Thank you for the RFC.

Currently the space key is somewhat human usable, and used in CQL: https://developer.atlassian.com/cloud/confluence/cql-fields/#space .

My question is: How can users search/select spaces with CQL after this change?

3 Likes

Will these space aliases also end up in the resource identifiers in a page’s storage format, or will you ensure that only the original space key is stored in there?

2 Likes

So the plan is:

  1. introduce alias attribute, which can be renamed (that’s nice)
  2. current space keys will be “copied” to aliases (smart, I like that) :slight_smile:
  3. new space key is a unique (generated) ID

If there is a new space key (unique ID) what would be the purpose of the existing space id?

5 Likes

Hi Dhiral! Thanks for posting this.

First off, it seems like this is an EAP announcement and not an RFC. Should this perhaps have been placed in the announcement category?

Specific questions:

  1. Why create a new attribute for this? As @a.yessipovskiy mentioned, Confluence already has immutable space IDs. Space IDs are already available in many places, including parameter substitutions in the connect JSON ({space.id}), the existing space response object, and so on. They are also directly addressable by ID via the V2 APIs. Indeed, using space IDs in new development would be faster than using aliases, because space keys (and presumably space aliases) all require one further level of redirection to fetch the space ID from the V2 API.

Since this is being targeted for developer EAP release in a few weeks, my reading between the lines tells me that this feature is already mostly developed and that Atlassian is not accepting design suggestions.

  1. Some REST APIs require the space key as a query parameter, so apps need to sanitize user-provided space keys (and now presumably aliases as well). Will there be any changes to the set of acceptable characters in a space key, or in the new space alias? I believe it is currently limited to [^~0-9A-Za-z]+.
8 Likes

Hi Marc

There is no change in the way we use space keys in CQL search; additionally, the same key field will also support space aliases as well.

@jens
The space alias will not be stored in the page’s storage format, and it is also recommended that app developers refrain from using aliases to store application data.

1 Like

@a.yessipovskiy
Space IDs are primary identifiers and it is recommended to use them to access spaces. Support for the Space key will remain in place, as many applications extensively utilize it.

1 Like

This is not a public EAP. The Initial EAP is exclusively for developers. An EAP announcement will be made when it’s ready for a closed or public EAP. Due to potential changes for developers, such as avoiding the use of URLs to parse keys and modifications in create space APIs (deprecation notice), we believe it’s more suitable for RFC.

  1. Space IDs remain the primary identifiers and are recommended for accessing spaces. Our app developers have extensively utilized space keys for a long time. Some applications rely on space keys for data storage and indexing. Introducing mutability to space keys would represent a significant change for numerous app developers, potentially affecting their current development schedules.

  2. The set of acceptable characters in an alias will not change; it will be exactly the same as the Space key.

Addressing the question about the difference between space keys and space aliases, space aliases will be mutable whilst space keys are immutable.

“After a transition period, the provided Space key will be stored as a Space Alias and the Space Key will be an internally generated ID. No existing Space keys will be changed.”

  1. Is there a limit to the number of changes to a Space Alias that can be made for any given Space?
    If not limited, the wording of:

In addition, any stored URLs with a Space key or Space Alias will continue to work even if a new Space Alias is applied to a Space.

suggests that the latest Space Key and Space Alias would work, and searching Rest APIs with either the Space Key or Space Alias would find the given Space.
If multiple Alias changes can be made, what is the impact on both URL with a historic Alias, and API searches with historic Alias(es)?

  1. If the context will return the most recent Space Alias, along with the Space Key/ID, is there a way to retrieve Space Alias history for a given Space?

(Would love to test the developer EAP for this - have installed and accepted the DCP canary app, but the Space context when rendering a Forge addon does not include the new space alias)

Hi @DennyMiller

Currently, there is a maximum of 10 aliases. If this limit is a problem, please comment.

  1. Web links will be redirected to the latest alias. All APIs will function properly with historic aliases, but we strongly advise against storing aliases. Instead, we recommend utilizing our V2 Space APIs to obtain the space ID for subsequent data processing purposes.

  2. The Public API will not be available in the initial release, but it will be added if there is sufficient interest in the future.

The feature is currently not enabled. We will notify the developer community once it becomes available for developer EAP.

1 Like

That endpoint should be /spaces/{id|key|alias}

You handle the complexity on your end.

What complexity? Think through what steps a developer would need to do if they’re extracting a space URL from a page, using regex to extract the id/key/alias, and then trying to hit the API to fetch that space.

4 Likes

Hi Dhiral,

Thanks for the clarifications about the format of the space keys/aliases.

Will the space alias be made available through substitution parameters in the Connect JSON (such as {space.alias})?

Scott

In addition, any stored URLs with a Space key or Space Alias will continue to work even if a new Space Alias is applied to a Space.

Is it safe to assume that changing existing Space A to use a new Space alias B would not be possible when a space with Key/Alias B exists?

Links with previous space keys or aliases will be automatically redirected to the currently active alias. All APIs that require a space key will also support this functionality, ensuring that appropriate spaces are provided in response to older aliases.

Along the same idea, what is to stop a historic Alias into a new Space? If URLs for space keys work, wouldn’t this pose a scenario where Space alias redirects for one space could prevent navigation to a space with a matching key/alias?

The scenario that an admin wants a new space to have a specific Space key that is already taken, they can change the alias of existing space, and update new space alias to be the previous space key value. (E.g. existing Space A gets changed to RENAMED, and new Space B gets renamed to A.)

How would the redirect be handled in this case when navigating to A? Is it treated from the older Space historic Key of A, or the new Space with the updated Alias of A?

2 Likes