/
REST APIs

REST APIs

This page describes how to use REST APIs for Table Grid Next Generation for Jira Cloud. Our APIs endpoints are deployed outside of your Atlassian Site cause we are storing grid data using MongoDB, the root URL of all our endpoints is https://databuckets.net.

To summarize how to use our REST APIs:

  1. Generate an Atlassian API token with your user account, here is the documentation to learn how to generate a token: Manage API tokens for your Atlassian account | Atlassian Support

image-20240327-072536.png

  • From the dialog that appears, enter a memorable and concise Label for your token and click Create.

image-20240327-073126.png

  • Click Copy to clipboard, then paste the token to your script, or elsewhere to save

image-20240327-073141.png

  1. Validate your authentication using your Atlassian site REST APIs to be authenticated, see the Authorization part here in this documentation.

You can use this Postman collection to experiment with . To use it, import it in Postman, then set the appropriate values to collection variables (click on three dots → Edit → Variables). You can enter all values but accountId, then run "Get account id" script which automatically fills accountId variable for you.

image-20240404-075321.png

  1. Start to request data from your grid using our REST APIs endpoints

Contents

Postman Collection

Table Grid Cloud.postman_collection.json

Firstly, make sure to follow our Excerpt above to generate an Atlassian API token and validate your authentication.

You can use this Postman collection to experiment with Table Grid Cloud API. To use it, import it in Postman, then set the appropriate values to collection variables (click on three dots → Edit → Variables). You can enter all values but accountId, then run "Get account id" script which automatically fills accountId variable for you.

 

Authorization Basic authentication scheme is used for authentication. You can also use Table Grid Cloud postman collection for that. email:Email of your account jiraAPIToken:Get it on https://id.atlassian.com/manage-profile/security/api-tokens username: Username of your account (type your e-mail address) instanceName is the part of your Jira Cloud site name before the ".atlassian.net". tgcApiToken: Get it on "API Tokens" tab on "Manage your apps" page accountId: Select “Get account id” request → Click “Send” button. Then there will be a JSON will contain accountId like the picture below: Basic auth password is a token generated on "API Tokens" page. You need to provide these credentials for every request in the "Authorization" header. If your credentials are incorrect, their will be a error request like the example below: Please note that user need to complete the Authorization first before creating any requests in Postman, or else it will return results show status 401: Unauthorized.
Value Format Values in columns are stored in the following format: Checkboxes are stored as booleans. Integers, Numbers, Dates, DateTimes and Times are stored as numbers. Values of Date, DateTime and Time columns are stored in Unix time format in milliseconds. Strings, Textareas, Single Select Lists and Sequences are stored as strings. Value of a single select list is a string containing a selected item's title. Multi Select Lists are stored as lists of strings containing titles of selected items. Formulas are stored as numbers or strings depending on return type. Userlists are stored as Maps with the following entries: "accountId" contains user's account id, which uniquely identifies a user. "accountId" may be missing from the result of "Read Grid Data" method call if a user could not be found. When using "Add Grid Data" or "Update Grid Data" methods, "accountId" MUST be provided, and the rest of the entries are optional. "value" contains user's full name. "avatar" contains a link to user's avatar. The term empty value refers to nulls, empty strings and empty lists.

Methods

Get Grids API call: GET https://databuckets.net/rest/tgc/api/v1/grids Description: Returns all grids in a Jira Cloud instance QUERY PARAMETERS gridType string Filters the grid list by grid types. Use this parameter to retrieve only Grid Custom Field grids or both Classic Grid and Grid Custom Field grids in the response. Default: gridType is omitted, the endpoint returns Classic Grid only. Values: CUSTOMFIELD - returns Grid Custom Fields only. BOTH - returns both Classic Grids and Grid Custom Fields. Notes: The value is case-sensitive. Use CUSTOMFIELD or BOTH. Omitting gridType is intended for backward compatibility and returns Classic Grids only. Responses
Read Grid Data API call: GET https://databuckets.net/rest/tgc/api/v1/grids/{gridId}/issue/{issueIdOrKey} Description: Returns all the rows for a grid custom field and an issue Request PATH PARAMETERS gridId REQUIRED string Grid id. issueIdOrKey REQUIRED string The ID or key of the issue. QUERY PARAMETERS columnIds Array<string> A list of columns' ids to return for the Grid. This parameter accepts a comma-separated list. Note: All columns are returned by default.  Responses
Add Grid Data API call: POST https://databuckets.net/rest/tgc/api/v1/grids/{gridId}/issue/{issueIdOrKey} Description: Add rows to the Grid custom field Request PATH PARAMETERS gridId REQUIRED string Grid id. issueIdOrKey REQUIRED string The ID or key of the issue. QUERY PARAMETERS acceptInvalidSelectListOption boolean Indicates whether to accept invalid values for single or multi-select list columns. Default: false Note: When set to true, the system will accept values that are not currently defined in the select list options. bypassRequiredValidation boolean Indicates whether to bypass required column validation when adding a row. Default: false Note: When set to true, the system will accept the request even if one or more required columns are left empty. This applies to both individually required columns and grids with the "Require All Columns" setting enabled. BODY Example (application/json) { "rows":[ { "status":"Open", "user":"Stephen Curry", "summary":"New row" } ] } Responses
Update Grid Data API call: PUT https://databuckets.net/rest/tgc/api/v1/grids/{gridId}/issue/{issueIdOrKey} Description: Update rows of the Grid custom field Request PATH PARAMETERS gridId REQUIRED string Grid id. issueIdOrKey REQUIRED string The ID or key of the issue. QUERY PARAMETERS acceptInvalidSelectListOption boolean Indicates whether to accept invalid values for single or multi-select list columns. Default: false Note: When set to true, the system will accept values that are not currently defined in the select list options. bypassRequiredValidation boolean Indicates whether to bypass required column validation when updating a row. Default: false Note: When set to true, the system will accept the request even if one or more required columns are left empty. This applies to both individually required columns and grids with the "Require All Columns" setting enabled. BODY Example (application/json) { "rows":[ { "rowId":"row_b089f167-9475-401b-88bd-2c2d25052196", "columns":{ "status":"Open", "user":"Blake Griffin", "summary":"Updated value" } } ] } Responses
Delete Grid Data API call: DELETE https://databuckets.net/rest/tgc/api/v1/grids/{gridId}/issue/{issueIdOrKey} Description: Delete rows of the Grid custom field Request PATH PARAMETERS gridId REQUIRED string Grid id. issueIdOrKey REQUIRED string The ID or key of the issue. BODY Example (application/json) { "rows":[ "rowId_823e747c-a38a-4f14-8fe4-2ee565124503", "rowId_7424bd1a-4c1f-404c-988b-1059756f3d72" ] } Responses