6 keys to designing a successful API integration

You’re building a new app, and have made your way through the 5 must-do tasks for any new API integration — nice work! Now it’s time to take things to the next level: let’s learn the 6 keys to designing a successful API integration.

1. Have a plan

When you’re building a new app, two documents define your plan:

The functional spec defines the app’s capabilities, visual appearance, and how users will interact with it.
The technical spec defines the technical design for building an app that fulfills the requirements described by the functional spec.

Creating these docs before you start writing code will greatly improve the efficiency of your development process — not to mention increase your odds of success. When it comes to using APIs, your technical spec should (at a minimum) contain details about:

Which APIs your app will use.
- e.g., DocuSign API, Google Docs API, etc.

Which SDK your app will use.^*

Which API operations (or corresponding SDK functions) your app will call.
- e.g., Create Envelope, Get Documents, etc.

When your app will call each API operation (or SDK function).
- i.e., What action in the app triggers the calling of each operation (function)?

The expected input and output of each API operation (or SDK function).
- i.e., The structure and contents of each API operation’s (or function’s) request and response.

How your app will respond to the various response codes that each API operation (or SDK function) may return. e.g.,
- If the Get Documents operation returns a 200 (success) response, display the list of documents.
- If the Get Documents operation returns a 401 (unauthorized) response, display a message to indicate that the current user lacks appropriate permissions to view the list of the documents.

^*SDK – yay or nay?

One of the key decisions you’ll make during the planning process is whether to use an SDK (client library) or to write all the API-related code in your app from scratch. Use an SDK if one is available — it’ll save you a ton of time!

A good SDK:

Greatly reduces the amount of code you need to write to interact with an API.
Provides a simple interface that’s easy for developers to understand and use.
Is designed with API best practices in mind and interacts with the underlying API in an optimal manner.
Provides comprehensive intellisense in your IDE, eliminating the need to constantly reference API documentation while coding.

Don’t be deterred by the learning curve you’ll encounter when using an SDK for the first time. Choosing not to use an SDK because of the slight learning curve is like saying “Learning to drive a car is complicated…I can just walk everywhere I need to go.” Take my word for it: Invest the time in learning to use SDKs, and you’ll never look back.

2. Follow best practices

When it comes to building an API integration, there are lots of ways to go about it. But how can you know the best way? Developer resources for the product or service you’re integrating with will demonstrate best practices for integrating with its API.

API documentation often contains quick starts and/or tutorials that illustrate best practices for using the API. Also look for code snippets in the docs that show how to use each API operation via the SDK of your choice.

Code samples can illustrate best practices AND greatly accelerate the pace of building an API integration. Check the Dev Center, API docs, and GitHub organization for the product or service you’re integrating with for code samples that are relevant to your integration scenarios.

Sample applications can illustrate best practices AND provide a huge leap forward in building a new API integration, if you can find one that contains functionality similar to what you’re trying to build. Check the Dev Center, API docs, and GitHub organization for the product or service you’re integrating for sample apps you may use as a basis for building (at least parts of) your API integration.

SDKs not only provide an efficient way to use an API, they can also be a valuable source of sample code. Curious how to perform a certain operation using an SDK? If the SDK is open-source (i.e., you’re able to view the SDK source files on GitHub), check the SDK’s README for info about code samples. Also, review the SDK’s unit test code on GitHub (commonly located inside a folder named test) to see how it’s calling the various API operations and processing the responses.

As shown in following screenshot, the DocuSign page on Github contains language-specific repositories for SDKs, code examples, and sample applications. A treasure trove of developer resources!

3. Be efficient: Use bulk-enabled operations

When designing your API integration, look for opportunities to use bulk-enabled operations when possible. A bulk-enabled API operation allows you to add, update, or delete multiple items using a single API request. For example, if you want to add 10 rows to a sheet in Smartsheet, you should do so using a single Add Row(s) request, rather than issuing 10 separate requests (one for each row).

Bulk-enabled operations improve efficiency by reducing the number of outbound calls you have to make. Using them also reduces your chances of exceeding an API’s rate limit (the number of API calls an app or user can make within a given time period) — since each bulk operation counts as only one request toward the limit.

4. Be practical: Adhere to rate limits

And speaking of rate limits…be sure to know the rate limits of the API you’re using, and design your integration accordingly. For example, the Smartsheet API currently enforces a rate limit of 300 requests per minute per API access token. If Smartsheet receives more than 300 requests within a minute from the same access token, it’ll respond with a 429 HTTP status code and the following JSON response body:

{
  'errorCode': 4003,
  'message': 'Rate limit exceeded.'
}

When designing your integration, you should:

Avoid implementing scenarios that are likely to exceed documented rate limits for the API you’re using.
Implement error handling logic to gracefully handle rate limit errors. For example, you might choose to implement exponential backoff in response to a rate limit error — an error handling strategy where you periodically retry a failed request with progressively longer wait times between retries, until either the request succeeds or a certain number of retry attempts is reached.

5. Be smart: Handle errors appropriately

And speaking of error handling…be sure to design your integration to handle errors appropriately. For example:

A 400 Bad Request response indicates a problem with structure or contents of the request. Do not simply retry the same exact request, as it will just fail again. Instead, fix the structure and/or contents of the API request and then reissue it.

A 503 Service Unavailable response indicates that the server is unable to handle incoming requests — often either because the server is too busy or is down for maintenance. In this scenario, it makes sense to retry your request with exponential backoff (i.e., waiting progressively longer between retries, until either the request succeeds or a certain number of retry attempts is reached).

API docs should contain the information you’ll need to implement appropriate error handling strategies in your app.

6. Be diligent: Implement logging

Lastly, consider logging the requests that your app issues and the responses it receives back (including detailed error codes and messages) to a file. When things go awry and you need to troubleshoot a failing API request, having access to this type of log file is invaluable. It’ll streamline your troubleshooting process and accelerate time to resolution.

So there you have it…

…6 keys to designing a successful API integration:

Have a plan.
Follow best practices.
Be efficient: Use bulk-enabled operations.
Be practical: Adhere to rate limiting guidelines.
Be smart: Handle errors appropriately.
Be diligent: Implement logging.

Give these factors the attention they deserve, and you’ll improve the performance, stability, and maintainability of your API integration.

Unfortunately, even well-designed API integrations still encounter problems from time to time. Check out the next post for some tips about troubleshooting API issues. But first — a quick knowledge check:

Twitter