Home Page > Integration > REST API > Fields > Grid Data Format

Grid Data Format

Base Format

Grids are available for any Field that is using the grid field_display_type. Instead of a single value, they will be represented by an object. That object will contain the following:

{
    "limit": "<int>",
    "offset": "<int>",
    "total": "<<int>",
    "rows": [
        {
            "_row": "<int>",
            "<grid_column_code>": "<grid column data type>"
        }
    ]
}

 

For example, here is some data for a grid Field with the rest_code of roles. It contains 4 GridColumns each with the code: end_date, project_role, role_description, start_date.

[
    {
        "id": "1",
        "roles": {
            "limit": 10,
            "offset": 0,
            "rows": [
                {
                    "_row": "1",
                    "end_date": 0,
                    "project_role": "Lead Engineer",
                    "role_description": "Oversee All Design and Engineering",
                    "start_date": "20150102000000"
                }
            ],
            "total": "1"
        }
    }
]

 

  • limit - Used to tell how many rows maximum will be showed or referenced when updating
  • offset - How many rows to skip from the start before the rows array starts
  • total - Total number of rows in this grid
  • rows - The array of the rows returned for this grid
    • _row - This gives the current row number. Can be used to move a row when updating, explained below.

GET Parameters for Grids

The offset and limit on grid objects can be controlled with URL parameters. The two universal ones are:

  • gridLimit - Limit for all grids that don't have a specific limit set, default 10, 0 will make the grid return all rows
  • gridOffset - Offset for all grids that don't have a specific offset set, default 0

 

To give a specific offset and limit, you would use <rest_code>[offset] and <rest_code>[limit]. For instance, if you had a grid Field with rest_code patents that you wanted the 6th row from while getting the first 3 rows for the other grid fields, you would use the following URL:

/REST/1/Projects/1/Fields?gridLimit=3&patents[offset]=5&patents[limit]=1

 

This would result with patents having an offset of 5 and limit of 1 while any other grid fields would have offset of 0 and limit of 3.


Editing Row Data

Just set the offset and limit to include the specific row or rows to be edited and change the data. Only the fields that need changing need be included but including data which has not been changed will not do anything than excluding it. For example, this changes the start_date field from above without modifying anything else:

[
    {
        "id": "1",
        "roles": {
            "limit": 1,
            "offset": 0,
            "rows": [
                {
                    "start_date": "20141102000000"
                }
            ]
        }
    }
]

Adding Rows to Grids

To add rows, just set the offset to the total and include new rows in the rows array. Using the above example, here is adding a new row:

[
    {
        "id": "1",
        "roles": {
            "limit": 1,
            "offset": 1,
            "rows": [
                {
                    "end_date": 0,
                    "project_role": "Junior Engineer",
                    "role_description": "Support Design and Engineering",
                    "start_date": "20141002000000"
                }
            ]
        }
    }
]

 

It is also acceptable to edit the last rows by having the offset below total and include new rows that would go beyond the currently stored rows. Here is an example where the description is changed from before on the existing row plus a new row added.

[
    {
        "id": "1",
        "roles": {
            "limit": 2,
            "offset": 0,
            "rows": [
                {
                    "role_description": "Oversee All Design and Engineering including Junion Engineers"
                },
                {
                    "end_date": 0,
                    "project_role": "Junior Engineer",
                    "role_description": "Support Design and Engineering",
                    "start_date": "20141002000000"
                }
            ]
        }
    }
]

Deleting Rows

To remove a row, include the row within the offset/limit range and leave the corresponding value to be null or undefined. For example, to delete the second row added above:

[
    {
        "id": "1",
        "roles": {
            "limit": 1,
            "offset": 1,
            "rows": []
        }
    }
]

Note: This can delete multiple rows. So take care of limit and offset values when editing grid data to make sure it lines up with the desired affect. It is highly recommended to work on one row at a time when making changes.


Moving Rows

The special field _row not only tells what number a row is on GET, but can be used for changing the order of rows. Let's say after adding our new row above, we wanted to change row 2 to be row 1. This can be accomplished with:

[
    {
        "id": "1",
        "roles": {
            "limit": 1,
            "offset": 1,
            "rows": [
                {
                    "_row": "1"
                }
            ]
        }
    }
]

This will bump the current row 1 down to be row 2. If there were multiple rows, then all rows after the listed move will be bumped down as well. 

Last modified

Tags

This page has no custom tags.

Classifications

This page has no classifications.