Entry points

There are various entry points into the REST API. They correspond to the data contexts.

There are additional authentication entry points for signing in and signing out.

Overview

An instance or tenant consists of the following hierarchical levels: Site > Spaces > Workspaces

Every space has at least one active workspace, the default workspace. The original name of this workspace is default_workspace. It can be renamed, but cannot be deleted.

These contexts are also the entry points into the REST API. Every entity exists in one of these contexts.

Entity type Description
Shared

To facilitate sharing between workspaces, entities are stored in a shared_data resource. Shared entities stored here are available to all associated workspaces. Shared entities include items like rules, user-defined lists, and releases.
Non-shared

Entities that are not shared are stored in each individual workspace.

Space

Space entities are entities that are defined at the space level, regardless of whether the space is shared or isolated. These entities include users, API keys, and more. These entities are available from the space context.

Note: Unless indicated otherwise, the documentation and examples assume the context of workspaces in an isolated space.

Back to top

Entry point URLs

Use these entry point URLs to find the REST API.

Context

Entry point

Site

http[s]://<server>:<port>/admin/*

  • Applies to site-level entities, such as database servers and spaces.
  • Permissions of the site admin are enforced.

Space

http[s]://<server>:<port>/api/shared_spaces/<space_id>/*

  • Applies to resources that are shared for all workspaces, such as workspaces and users.

  • The space is also represented as an entity. It exists in the site context: /admin/shared_spaces

  • /api/shared_spaces can be accessed either by id (string) or by logical_name (string).

  • Permissions of the space admin are enforced. For example, space admins can create and delete workspaces.
Shared area

 

http[s]://<server>:<port>/api/shared_spaces/<space_id>/shared_area

Where: 

  • space_id is a unique identifier / logical string.

  • shared_area is a set keyword representing the special area in the space that contains shared assets.

  • Permissions of the space admin are enforced.

Workspace

http[s]://<server>:<port>/api/shared_spaces/<space_id>/workspaces/<workspace_id>/*

Where: 

  • space_id is a unique identifier / logical string.

  • workspace_id is a unique identifier / logical string.

  • A workspace is an entity (resource) and is located in a shared space context. A workspace can be seen from the workspace context entry point, exactly as the model dictates.

  • Permissions on the workspace level are enforced.

Throughout this document, the example URIs are abbreviated, without the server and port context.

http://<server>:<port>/api/shared_spaces/<space_id>/workspaces/<workspace_id>/<entities>

Becomes:

.../api/shared_spaces/<space_id>/workspaces/<workspace_id>/<entities>

Back to top

Authentication entry points

The sign_in REST singleton resource lets you authenticate, sign in to the REST API using JSON authentication.

You can also sign in by sending a header with user credentials for each request using basic authentication.

For details, see Authentication.

Back to top

Non-authenticated entry points

It is possible for your REST API to navigate to an entity URL when not yet authenticated, such as when copying a URL or sending an email with a link to an entity. After prompting for authentication, you are redirected to the details of the entity.

Specify entity-navigation as follows: 

http[s]://<hostname>/ui/entity-navigation?p=<shared_space_id>/<workspace_id>&entityType=work_item&id=<id>

After authentication, this redirects to: 

http[s]://<hostname>/ui/?p=<shared_space_id>/<workspace_id>#/entity-navigation?entityType=work_item&id=<id>

Back to top

See also: