Aliases
=======

An **alias** is a unique identifier for a digital entity that can be
used as an alternative ID to the one generated by Dockstore. A digital
entity refers to a tool, workflow, organization or collection on
Dockstore. Aliases are only unique within entity types, so you could use
the alias *foobar* for both a tool and an organization. Tools and
workflows are treated as a single entity type.

Currently the only way to add an alias to an entity is through our API.
You can use our `Swagger
UI <https://dockstore.org/api/static/swagger-ui/index.html#>`__ to add
an alias.

**Some things to note:**

* You can create multiple aliases per digital entity, however they must all be unique
* Aliases are restricted to alphanumerical strings that are case-insensitive and can contain internal hyphens
* An alias cannot be removed

Tools and Workflows
-------------------

If you would like to setup aliases for your tool or workflow, you can
now do so through our API. Aliases are useful for when you would like to
publish your work on Dockstore and other Dockstore-like sites. You can
use an alias to give this tool a unique name that could potentially be
valid across all sites, independent of site specific naming conventions.

You can link to a tool that has the alias ``MyTool`` using the link
https://dockstore.org/aliases/tools/MyTool. Similarly, you can link to a
workflow that has the alias ``MyWorkflow`` using the link
https://dockstore.org/aliases/workflows/MyWorkflow. This is the
recommended way to link to tools and workflows, as names can be changed,
making linking by names quite fragile.

Use the ``/entries/{id}/aliases`` endpoint to add new aliases. You can
specify the aliases as a comma-delimited list.

Organizations and Collections
-----------------------------

The main use of an alias is as a permanent identifier for an entity that
is used to create a stable URL. Aliases can neither be changed nor
removed. For example, an institution that must change its name would
also like to modify its organization name in Dockstore. Similarly, a
collection might change its name over time to highlight the current
workflows in use. By providing an alias, a stable URL is created for a
collection or organization regardless of its name.

You can link to an organization that has the alias ``MyOrganization``
using the link
https://dockstore.org/aliases/organizations/MyOrganization. Similarly,
you can link to a collection that has the alias ``MyCollection`` using
the link https://dockstore.org/aliases/collections/MyCollection. This is
the recommended way to link to organizations and collections, as names
can be changed, making linking by names quite fragile.

If you would like to setup aliases for your organization or collection,
you must first ensure that the corresponding organization has been
approved. Then you can use one of the corresponding endpoints to create
the alias.

Use the ``/organizations/{id}/aliases`` endpoint to add an alias for an
organization.

Use the ``/organizations/collections/{id}/aliases`` endpoint to add an
alias for a collection.

.. discourse::
    :topic_identifier: 1567