New Features in the RingCentral.Net SDK 4.0
RingCentral.Net SDK 4.0 Release Notes
We just released RingCentral.Net SDK 4.0.0-beta 4, soon we will release a stable version. There are some major updates and new features available in this new version:
- Batch Get
- Cancel a Request
- Rate Limit Helper
- Auto Retry feature
- New sample code documentation
Please note that, some of these features have already been available for quite a while, but we decided to put them all in this article to make sure you are aware of them. Let’s go through these features one by one.
Batch Get
Let’s say you have 20 call log IDs, how can you get all of these call log records? The quickest solution is:
While this does work it will end up making 20 API calls to the RingCentral server. Not only is this a slow process, but also you might get throttled if you make API calls too fast.
With Batch Get, you can do it with one and only one API call:
But what if there are invalid call log IDs in the batch request? In that case batchResponse.content will be null and batchResponse.error will provide you with detailed error information.
I will probably write a new article to cover more details of Batch Get. I will stop here on this topic for this article, because there is a lot of information to add. If you have questions or get stuck I have some resources listed for you at the very bottom.
Cancel a Request
This is a feature request from a user of the RingCentral.Net SDK. If for some reason a API call takes too long or you just want it to timeout after a period of time, you need a way to cancel an API request.
RingCentral.Net is powered by HttpClient and its SendAsync method supports a cancellationToken parameter. So HTTP request cancellation is supported by HttpClient out of box. We added this feature to RingCentral.Net SDK to help you do this:
Rate Limit Helper
Rate Limit handling is a big topic. My colleague Phong Vu wrote a great article named RingCentral API Rate Limit Explained. Please read it if you haven’t done so. RingCentral APIs are grouped into four groups: Heavy, Medium, Light & Auth. Each group has a rate limit. If you exceed the rate limit, you will receive an HTTP 429 error.
There are different strategies to handle rate limit. I cover some of these issues in my other article Best Practices to Send Large Volumes of SMS. In order to precisely control the API call speed to avoid hitting a rate limit, you need to read the X-Rate-* headers of the API responses.
To make this easier we decided to provide some helper properties in the SDK in order to help you read the headers information. You can access it directly by rc.rateLimits, which you can do with this:
In your own code, you can use these properties like this:
Please note that the code above is just a sample. You may have different ideas/strategies to handle rate limit issues.
Auto Retry feature
This feature is very useful in the following scenarios:
- API server returns HTTP 503 error: service temporarily unavailable.
- You hit the rate limit HTTP 429 error.
You may want to retry the API calls several times with a progressive delay. We have this feature built in the SDK! To enable it:
rc.AutoRetry(baseDelay: 10000, maxRetryTimes: 10, retryableHttpStatusCodes: new[]{429, 503});Once this feature is enabled like shown above, all the API calls will do auto retry upon 429 & 503 HTTP errors up to 10 times, with a base delay 10 seconds, and increase in a progressive random manner.
To disable this feature:
rc.StopAutoRetry();New sample code documentation
We decided to show more useful content in the sample code documentation:
We have included Rate Limit Group, App Permission and User Permission . That information is also available on the API reference pages, but we just provide them in the C# code samples page for your convenience.
Summary
That’s it about the RingCentral.Net SDK 4.0! We’d love your feedback! Do you have ideas or feature requests? We would be glad to include them in next major release of the SDK: RingCentral.Net SDK 5.0! Please leave comments below.
To learn even more about other features we have make sure to visit our developer site and if you’re ever stuck make sure to go to our developer forum.
Want to stay up to date and in the know about new APIs and features? Join our Game Changer Program and earn great rewards for building your skills and learning more about RingCentral!
