REST API

You can use Jira's REST API to view, create or change data within the STAGIL Table field. The following section will help you to set up your API requests.

Content

REQUESTS

Read table (going to be deprecated)

First, look for your STAGIL Table custom field's ID and the issue ID from which you want to pull the data. The GET request has to look like this:

  • Example URL: https://yourjiraURL.xyz/rest/api/2/issue/DEV-6?fields=customfield_10100&expand=renderedFields

  • "DEV-6" is your issue key

  • "customfield_10100 is your custom field ID of the Table custom field

With this request, you will get all the tabular data from the table.


GET ROW SUM

We have a special URL to access the sum row of a table. When you let STAGIL Table automatically sum up the values of your table's columns, you can get the sum value by using following URL:

 

GET TABLE SUM (going to be deprecated)

Please note that this request is going to be replaced by the GET TABLE SUM request down below.

If you want to directly get the sum of your table, you can use the following syntax:

  • BASEURL/rest/stj/1.0/table/sum/customfield/{customfield_ID}/issue/{issuekey}

  • Example URL: https://yourjiraURL.com/rest/stj/table/sum/customfield/22007/issue/KEY-123

It will give you the following data: Arrays of table sums: columnID, columnsum, columnID, columnsum, columnID, columnsum.

Example output for a table containing only one row that should be summed up:

GET TABLE SUM

If you want to directly get the sum of your table, you can use the following syntax:

  • BASEURL/rest/stj/1.0/api/table/sum/customfield/{customFieldId}/issue/{issueIdOrKey}

  • Example URL: https://yourjiraURL.com/rest/stj/1.0/api/table/sum/customfield/22007/issue/KEY-4

It will give you the following data: Arrays of table sums: columnID, columnsum, columnID, columnsum, columnID, columnsum.

Response:

 

GET FIELD

This request can be used to get information about the configuration of a STAGIL tables custom field. This means you will get information like id, default value, column type, max/min values, read only etc. for each row in your table:

  • BASEURL/rest/stj/1.0/api/table/fields/{customfieldID}

  • Example URL: https://yourjiraURL.com/rest/stj/1.0/api/table/fields/23804

Response: An array which contains configuration information about each row id per index step.

 

 

GET FIELD SUM

If you want to get the sum of just one field you can use the following request url:

  • BASEURL/rest/stj/1.0/api/table/sum/customfield/{customFieldId}/issue/{issueIdOrKey}/field/{fieldId}

  • You can retrieve the field ID from the table field configuration screen.

  • Example URL: http://yourjiraURL/rest/stj/1.0/api/table/sum/customfield/22007/issue/DEMO-4/field/10

Response:

GET CSV FILE

You can also get a csv export of your table by using REST API:

  • URL: https://yourjiraURL/rest/stj/1.0/api/table/{fieldConfigId}/{issueIdOrKey}/COMMA/csv

  • Response: you will receive the data of your table in csv format (separator = comma)

PUT Request

When you want to change certain rows of your table, you need to use the following API call configuration:

  • URL: https://yourjiraURL.xyz/rest/stj/1.0/table/data/rowID

  • Headers:

    • Your type of authorization

    • Content-Type: application/json;charset=UTF-8;

    • Accept: application/json;

  • You can get the row ID from the GET request, looking at the "id" of the row you want to modify.

  • URL example: http://localhost:8080/rest/stj/1.0/table/data/123

  • With the GET request you can also see all the available fields and the structure of the table data. When you have drop-down, text or user columns, you only need the "field-1" part of the body. The "field-1-html" or "field-1-name" is not needed and will be added automatically. At the end of the body you need to add the custom field ID and the issue ID.

  • Example body: {"orderPosition":9,"id":47,"field-1": "Customer 7", "field-3": [2], "field-5": "anorth", "field-6": [8], "customFieldId":11501,"issueId":"11706"}
    This structure is simply retrieved from the GET request and you only modify the fields that you want to change. In this example, field-1 is a text field, field-3 and field-6 are select lists and field-5 is a user picker.

  • Please make sure to include all the used columns of your row in your PUT request. Missing columns will be overwritten with empty values!

UPDATE ROW

To update an existing row in your table you can use this request:

  • URL:http://yourjiraURL/rest/stj/1.0/api/table/data/customField/{customFieldId}/issue/{issueIdOrKey}/row/{rowId}

  • The row id can be found in the concrete table in your issue:



POST Requests

CREATE ROW (going to be deprecated)

Please note that this request is going to be replaced by the CREATE ROW request down below.

To create a new row for a table, please use this POST request, which is very similar to the PUT request:

  • URL: https://yourjiraURL.xyz/rest/stj/1.0/table/data/

  • Headers: Same like PUT request

  • In the body of the POST request, you do not need to include values for the orderPosition and the id. The new row will automatically be added at the end of the table.

  • Example body: {"field-1": "Customer 8", "field-3": [2], "field-5": "anorth", "field-6": [8], "customFieldId":11501,"issueId":"11706"}
    This example's structure is the same like in the PUT request example.

CREATE ROW

To create a new row in your table you can use this request:

  • BASEURL/rest/stj/1.0/api/table/data/customField/{{customFieldId}}/issue/{{issueIdOrKey}}

  • Example URL: https://yourjiraURL/rest/stj/1.0/api/table/data/customField/22504/issue/189038

  • In the body of the POST request, you do not need to include values for the orderPosition and the id. The new row will automatically be added at the end of the table.

  • Example body:  { "field-35": 2, "field-34": "some example text", "field-36": 22.2, "field-37": "someuser", "field-38": "2021-02-10" }

DELETE ROW (going to be deprecated)

Please note that this request is going to be replaced by the DELETE ROW request down below.

To delete rows of your table, simply take the row ID that you get from using the GET request and add it to the URL:

  • URL: https://yourjiraURL.xyz/rest/stj/1.0/table/data/rowID

DELETE ROW

To delete single rows in your table you can use this request:

  • URL: http://yourjiraURL/rest/stj/1.0/api/table/data/customField/{customFieldId}/issue/{issueIdOrKey}/row/{rowId}

  • The row id can be found in the concrete table in your issue:

Error Codes

© 2023, STAGIL