From the Trenches: Working with Headers in Docusign SDKs

•

Summary•3 min read

Learn how you can get useful information from the API HTTP headers while still using the eSignature SDKs.

Additional resources

Additional resources

While the Docusign eSignature REST API SDKs can abstract away the need to manage individual HTTP packets, there are times when it is helpful to dig in deeper and see more information about what is happening when an application calls Docusign's eSignature API. For this reason, the SDKs offer variant methods that include HTTP information.

For example, the C# SDK offers two similar methods: EnvelopesApi.CreateEnvelope() and EnvelopesApi.CreateEnvelopeWithHttpInfo(). While the two perform the same function - creating an envelope - they differ in the response object they provide your application. The CreateEnvelope method simply returns an EnvelopeSummary, in which the EnvelopeId and Status are available. The CreateEnvelopeWithHttpInfo() method wraps that EnvelopeSummary in an ApiResponse object, which includes the EnvelopeSummary in the Data object as well as the HTTP response code and the packet's headers.

As per API Resource Limits, most Docusign API calls will include a set of headers that will aid in tracking an account's API Limit usage. To access these using an SDK, only a small amount of refactoring is necessary:

First, update the method to include HTTP info, and modify the expected response object type accordingly:
ApiResponse results = envelopesApi.CreateEnvelopeWithHttpInfo(accountId, envelopeDefinition);
Values that were previously available at the root level are now under the Data parameter. For example, to pull the EnvelopeId:
string envelopeId = results.Data.EnvelopeId;
The response headers can also be pulled and analyzed:
```
results.Headers.TryGetValue("X-RateLimit-Remaining", out string remaining);
results.Headers.TryGetValue("X-RateLimit-Reset", out string reset);
Console.WriteLine("API calls remaining: " + remaining);
Console.WriteLine("Next Reset: " + reset); // Unix timestamp
```

With this information, an application can then be aware of its limit and warn a user before taking bulk actions that would otherwise take an account over the limit. It would also be possible to track how low the remaining value gets each hour, and fire a warning if it is regularly exceeding a comfortable threshold.

The Docusign eSignature REST API also offers an optional header to track processing times, which is useful when attempting to identify the cause of delays in a workflow. To use the TimeTrack function, you'll need to add an additional header to your outgoing API call: The header's Key should be "X-Docusign-TimeTrack" and the Value can either be empty, or an arbitrary value that Docusign will return in the response.

To add a header using the C# SDK:

apiClient.Configuration.AddDefaultHeader("X-Docusign-TimeTrack", "");

If this header is present in the call to the API, the eSignature API will return timestamps of when the call hit Docusign, and when Docusign response was sent:

"REST0_Start,2019-10-30T20:08:58.6081938Z;REST0_End,2019-10-30T20:08:59.9675791Z"

By parsing and comparing these two timestamps, one can identify if a delayed response was due to processing time on the Docusign side or network latency.