When designing and building an API integration, it’s easy to become so focused on the details of operations, attributes, and parameters that you fail to consider factors that could significantly impact the performance, stability, and maintenance of your integration.
Giving such factors the attention they deserve can mean the difference between an integration that is unreliable and one that is rock-solid. To ensure that your integration is the best that it can be, we strongly recommend incorporating these four Smartsheet API best practices:
1. Be efficient: Use “bulk”-enabled operations
For maximum efficiency, use bulk-enabled API operations whenever possible. A bulk-enabled API operation allows you to add, update, or delete multiple items using a single API request.
For example, if you need to update 10 rows within a sheet, do so using a single Update Rows request, rather than executing 10 separate requests (one for each row).
Bulk-enabled operations improve efficiency by dramatically reducing the number of outbound calls your integration has to make. This reduces your chances of hitting the rate limit (since each bulk operation counts as only one request toward the limit).
The following API operations currently allow you to complete the following tasks in bulk:
We’ll be adding more “bulk”-enabled operations in the future, so be on the lookout for those additional opportunities to improve efficiency. And remember, it’s a best practice to do things in bulk whenever possible.
Tip: Allow for partial success
Usually, when an error is thrown during a bulk operation, the default behavior is to have the entire operation fail. For example, if you make a request to Update Rows and one of the row objects in the request is invalid, the whole operation will fail and none of the rows will be updated.
However, you have the option to allow for partial success on bulk requests. Allowing partial success will allow for the successful portions of a request to be carried out even if there are errors thrown during the operation.
2. Be practical: Adhere to rate limiting guidelines
Handle "rate limit exceeded" error
The Smartsheet API currently imposes a rate limit of 300 requests per minute per access token.
Certain resource-intensive operations, such as attaching a file or getting cell history, count as 10 requests toward the rate limit. If you exceed this rate limit, subsequent API requests (within a one-minute period) will return a 429 HTTP status code, along with the following JSON response body:
{
“errorCode”: 4003,
“message”: “Rate limit exceeded.”
}
We recommend that you design your integration to gracefully handle this rate limit error. One way to accomplish this is to have your integration sleep for 60 seconds when the error is encountered, and then subsequently retry the request.
Alternatively, you might choose to implement exponential backoff, an error-handling strategy whereby you periodically retry a failed request with progressively longer wait times between retries, until either the request succeeds or the certain number of retry attempts is reached.
Avoid executing "rapid fire" updates
Additionally, we strongly recommend that you avoid executing API requests in rapid-fire succession to update a specific Smartsheet object over and over again within a very short period of time.
For example, if the only thing your integration does is execute an Update Rows request once every second for the same sheet, that would only amount to a total of 60 requests per minute — well within rate limiting guidelines.
However, updating the same object in such rapid succession could result in save errors that negatively impact both your integration as well as user experience within the Smartsheet platform.
To avoid this scenario, design your integration so that API requests are never executed with rapid-fire succession against the same Smartsheet object. For maximum efficiency, consider batching up changes and submitting them in a single request using a “bulk”-enabled operation (e.g. Update Rows or Add Columns).
Execute requests serially
We also strongly advise against executing multiple API requests in parallel to update a specific Smartsheet object. Doing so will result in reduced performance and will most likely result in errors due to save collisions.
To avoid this scenario, design your integration such that API requests to update a specific Smartsheet object are always executed serially: execute one request at time, and do not begin the next request until the previous request has completed.
3. Be smart: Handle errors appropriately
A successful API request will result in a 200 HTTP status code, along with data in the body of the response according to the operation performed. But what happens if something goes wrong and you get back something other than a 200 response? The ability to handle errors appropriately is a critical component of a quality API integration.
If a Smartsheet API request is not successful, the API returns a 4xx or 5xx HTTP status code, along with a JSON response body that specifies details about the error that occurred. For example, if you execute a GET Sheet request using an invalid (nonexistent) sheet Id, the response will return an HTTP status code of 404 with the following JSON response body:
{
“errorCode”: 1006,
“message”: “Not Found”
}
When should you retry?
A successful error-handling strategy requires that your integration recognize the difference between errors that can potentially be resolved by retrying the request and errors that should never be retried automatically.
The HTTP status code that’s returned with a response is your first indication as to the outcome of the request.
Error handling recommendations
In addition to the HTTP status code, you should also evaluate the Smartsheet-specific error code that’s returned in the response body for any unsuccessful request. For example:
{
“errorCode”: 1006,
“message”: “Not Found”
}
The API documentation specifies error handling recommendations for each Smartsheet-specific error code. We recommend that you use that information to implement error handling logic according to the following guidelines:
-
If the error code indicates a permanent error condition, do not retry the request.
-
If the error code indicates a problem that can be fixed, do not retry the request until the problem has been fixed.
-
If the error code indicates a problem that could be overcome by retrying the request after a period of time, retry the request using exponential backoff.
4. Be diligent: Implement logging
In an ideal world, your integration would function seamlessly from day one, and there would never be a need to troubleshoot issues of any kind.
Unfortunately, that’s rarely the case. When issues do arise, it’s important that your integration is capable of logging API requests and responses.
Having access to the raw requests and responses (including detailed error codes and error messages) when API issues emerge will streamline troubleshooting and accelerate time-to-resolution.
The following examples show the type of information that your application should log for API requests and responses:
Request: verb, URI, header(s), request body
POST https://api.smartsheet.com/2.0/sheets/4098273196697476/columns
Authorization: Bearer MY_TOKEN
Content-Type: application/json
Request body:
[
{
"title": "FIRST COLUMN - My New Column",
"index": 0,
"type": "TEXT_NUMBER"
},
{
"title": "FIRST COLUMN - My New Column",
"index": 1,
"type": "TEXT_NUMBER"
}
]
Response: HTTP status code, response body
HTTP status: 400 Bad Request
Response body:
{
"errorCode": 1133,
"message": "Column titles are not unique among input columns.",
"detail": {
"columnTitle": "FIRST COLUMN - My New Column"
}
}
Often times, having access to this information will enable you to identify and resolve the issue on your own. On occasions where that’s not the case, you can reach out to devrel@smartsheet.com for assistance. We will ask you for the above request/response information in order to troubleshoot.
You should implement API request and response logging when you first set up your integration, as it will make the experience run more efficiently.
Start building your integration
Whether you’re currently in the process of designing and building an integration with Smartsheet, or have built an integration previously, there’s no time like the present to incorporate the best practices that we’ve covered in this post.
In addition, we encourage you to make the most of the Smartsheet Developer Portal for resources and guidance discussed in this post all aimed to help accelerate the time it takes for you to get comfortable using the Smartsheet API and help you confidently deploy your solution.
Subscribe to the Smartsheet IT Newsletter for tips, strategies, and ideas focused on helping IT professionals increase their impact on their business.