Demystifying Query Parameters in the Smartsheet API

Ready to learn something simple that will have a major impact on your Smartsheet API integrations? Stop parsing huge payloads and start telling the API exactly what you need with query string parameters.

When a URL contains a ?, everything that follows is the query string. The query string can pass parameters that modify the behavior of an API. Two helpful tips when working with query string parameters:

1. Multiple parameters must be separated with an ampersand (&).
2. Parameters with multiple arguments are separated with a comma.

The Smartsheet API makes use of query string parameters to include or exclude certain data, control pagination, and modify the default behavior of the API.

In the Smartsheet API documentation, each endpoint that supports additional parameters has a Parameters section describing the supported query string parameters.

Let's start with an example GET sheet request:
/sheets/123456789?include=attachments,discussions&pageSize=30

This request is using the include parameter so the response will include all attachments and discussions. The request is also using the pageSize parameter so that only the first 30 rows of the sheet are returned.

In addition to working with raw API requests, query string parameters can be passed back with your Smartsheet SDK of choice. Each one supports query string parameters (although the implementation may differ).

• C#
• Java
• Node.js
• Python
• Ruby

Please refer to the Query Strings section of the Smartsheet API documentation and select the tab for your preferred programming language in the coding sample sidebar to see examples. Other code samples throughout the API docs may also contain example uses of query parameters.

Be aware that the documentation is focused on REST and JSON. If an endpoint in the documentation has a list of parameters, the actual implementation of query string parameters may vary to fall in line with that respective programming language. Things like naming, capitalization patterns, and how parameters are passed may be different between each SDK.

C Sharp

In the C# SDK, query string parameters to include and exclude data are set using objects.

Column column = smartsheet.SheetResources.ColumnResources.GetColumn(
  923173393803140,     // long sheetId
  782142855221832,     // long columnId
  new ColumnInclusion[] { ColumnInclusion.Filters }
)

Pagination is implemented with a PaginationParameters object, which accepts additional parameters.

PaginatedResult<Sheet> sheets = smartsheet.SheetResources.ListSheets(
  new SheetInclusion[] { SheetInclusion.SOURCE },
  new PaginationParameters(
    true,           // includeAll
    null,           // int pageSize
    null)           // int page
);

If you need to use a query string parameter and can’t find that object's name in our API docs, then the self-generated C# SDK documentation can be a helpful resource.

Java

In the Java SDK, query string parameters are implemented as Enums for includes and excludes.

Sheet results = smartsheet.sheetResources().createSheetFromTemplate(
  sheet,
  EnumSet.of(
    SheetTemplateInclusion.ATTACHMENTS,
    SheetTemplateInclusion.DATA,
    SheetTemplateInclusion.DISCUSSIONS)
);

However, pagination is implemented as a PaginationParameters object.

// Specify pagination parameter 'includeAll'
PaginationParameters page_params = new PaginationParameters()
  .setIncludeAll(true);

// Specify `include` parameters
EnumSet include_params = EnumSet.of(SourceInclusion.SOURCE);

// List Sheets with pagination and include parameters
PagedResult<Sheet> sheets = smartsheet.sheetResources().listSheets(include_params, page_params, null);

The Parameters section (in the API docs) of each respective endpoint is your best resource, but the self-generated Java SDK docs can be helpful, too.

Node.js

The Node implementation of query string parameters is quite straightforward.

// Set options
var options = {
  queryParameters: {
    include: "attachments",
    include: "source",
    includeAll: true
  }
};

// List sheets
smartsheet.sheets.listSheets(options)
    .then(function(response) {
        console.log(response);
    })
    .catch(function(error) {
        console.log(error);
    });

Properties are defined in the queryParameters object, wrapped in the options object, and passed into the SDK's methods.

Ruby

The Ruby implementation of query string parameters is quite similar to Node. Both use properties identical to what is listed in the API documentation.

response = smartsheet.sheets.list(params: {include:"attachments,source", includeAll:true })
sheets = response

The Ruby SDK's methods accept a params object that has properties for includes, excludes, and pagination behavior.

Python

In the Python SDK, query string parameters are defined by passing additional parameters into the methods built into the SDK.

# Include discussions, attachments, columns, and columnType
row = ss_client.Sheets.get_row(
  4583173393803140,       # sheet_id 
  2361756178769796,       # row_id 
  include='discussions,attachments,columns,columnType'
)

Pagination, includes, and excludes all use that same mechanism.

response = ss_client.Cells.get_cell_history(
  9283173393803140,       # sheet_id
  0123456789012345,       # row_id
  4567890123456789,       # column_id
  page_size=5,
  page=1)
pages = response.total_pages
revisions = response.data

Making pragmatic use of query string parameters can significantly improve your ability to build with the Smartsheet API. Query string parameters can help you include information outside the default API response or better control the API response you get back (i.e. size, number of results). Query strings parameters can be used directly when interacting with the Smartsheet API, but are also implemented in each of the Smartsheet SDKs.