REST API

Overview

The REST API for the Gantt Suite allows authorized users to programmatically interact with features of the app.

Important Notes:

1. This functionality must be explicitly enabled by an admin. API token creation permission.

2. By default, no user has access to the REST API unless permissions are configured.

Enabling REST API Access

To enable REST API access, an admin must:

1. Navigate to Manage Apps > Gantt Suite > Permissions > API Token Creation.

2. Specify the Jira groups that are allowed to access the REST API.

   • By default, the list of groups is empty, meaning no users can access the API.

Recommendation: Create a dedicated Jira group specifically for REST API access. This ensures easy management and does not affect other Jira permissions.

User API Token Management

Once the admin has configured groups for API access:

1. Users belonging to the allowed groups will see an API Token field in their User Settings page.

   • The User Settings page is accessible via a link above any Gantt chart. User settings.

Generating an API Token

1. Initially, the API Token field will be empty.

2. Users can generate a new API token by clicking the Generate button next to the field.

   • Each time the Generate button is clicked, a new token is generated, and the previous token becomes invalid.

3. Once a token is generated, additional buttons appear:

   • Delete: Removes the current API token.

   • Copy: Copies the API token to the clipboard.

Open

Important:

• Tokens are visible only to their owners.

• Admins do not have visibility into user tokens from UI.

Handling a Compromised Token

If an API token is compromised:

• The token owner can:

  • Generate a new token (invalidating the old one).

  • Delete the token.

• Admins can:

  • Remove the user from the group configured for REST API access.

    • This action only affects access to the Gantt Suite API and does not impact other Jira permissions.

  • Data Center only: Remove the compromised token from the database. The token details are stored in the table AO_0A5D37_REST_API. Admins can manually delete the relevant record to revoke access.

Making API Calls

Once a user has a valid API token, they can make API requests by including the token in the Authorization header as a Bearer Token.

Header Format

Base URLs

• Cloud: https://gsj.brizoit.com/gsj/rest/brizoit/gantt/api/1

• Data Center: https://<domain>/rest/brizoit/gantt/api/1

Replace <domain> with the URL of your Jira Server instance.

API Features

The REST API provides endpoints for managing the following entities:

1. Charts: Create, update, delete, and retrieve Gantt charts.

2. Baselines: Manage baselines for Gantt charts.

3. Resource Calendars: Define and manage resource calendars.

4. Teams: Create and manage teams.

5. Chart Shares: Share Gantt charts with users who don’t have Jira account.

For detailed endpoint specifications, refer to the YAML document provided on the Confluence page.

Best Practices

1. Secure Your Token:

   • Keep your API token confidential.

   • Immediately generate a new token if you suspect it has been compromised.

2. Use a Dedicated Group for API Access:

   • Creating a dedicated Jira group ensures precise control over API access and avoids unintended permissions changes for users.

3. Monitor and Manage Access:

   • Regularly review group memberships and remove users who no longer require API access.

API Specification

YAML document describing the API endpoints

Open

Viewing the YAML in Swagger Editor

To explore the endpoints using Swagger Editor:

1. Visit Swagger Editor.

2. Copy the contents of the YAML file.

3. Paste it into the editor on the left-hand side.

4. The endpoints, request details, and available operations will be displayed interactively on the right-hand side. This document contains all endpoint details, including request formats.