Demystifying Query Parameters in the Smartsheet API
Published on 06 February 2019
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:
- Multiple parameters must be separated with an ampersand (&).
- 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).
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.