SDKs makes the integration of REST APIs easier by packaging boilerplate code for developers.
Why do developers need help integrating APIs?
Let's take a look at the numbers.
Plaid has a REST API with 215 operations, 1346 schemas, and 215 parameters.
SnapTrade has a REST API with 91 operations, 125 schemas, and 183 parameters.
Twilio has a REST API with 199 operations, 152 schemas, and 874 parameters.
The complexity of these APIs can be daunting for developers who are under a time pressure to integrate an API and frustrating for API companies because onboarding is time consuming. Developers are required to parse tons of documentation and code while API companies must provide continuous support for a successful partnership. To make matters worse, developers can be using a programming language that nobody at the API company knows. To alleviate the pain, best-in-class API companies publish SDKs to accelerate the integration process.
So how does an SDK actually help?
Lets walkthrough an example in Python integrating Twilio's API without an SDK. Then we will rewrite our implementation using their SDK. Finally we will analyze the significant difference between implementations.
For this example we send an SMS and retrieve the sent SMS by ID.
Without an SDK
Import your favorite request library to make HTTP requests. In this case we are
using Python's requests library. Then lets initialize all our parameters.
Construct the target URL for our HTTP request. We found the URL from Twilio's documentation.
Construct our request body using the format from the documentation.
Construct our authentication credentials according to how Twilio receives
credentials and how the requests library performs basic
authentication
which in this case is a tuple where the first item is the username and the
second item is the password.
Make a POST request using the requests library and cross our fingers 🤞 that
we got all the previous steps right with no typos.
Deserialize the response from JSON and retrieve the sid field as shown in an
example response from the documentation.
To retrieve the message we construct a URL based on the format described in the documentation.
Make a GET request with the new URL while remembering to pass in the auth
variable we assigned earlier.
Import your favorite request library to make HTTP requests. In this case we are
using Python's requests library. Then lets initialize all our parameters.
Construct the target URL for our HTTP request. We found the URL from Twilio's documentation.
Construct our request body using the format from the documentation.
Construct our authentication credentials according to how Twilio receives
credentials and how the requests library performs basic
authentication
which in this case is a tuple where the first item is the username and the
second item is the password.
Make a POST request using the requests library and cross our fingers 🤞 that
we got all the previous steps right with no typos.
Deserialize the response from JSON and retrieve the sid field as shown in an
example response from the documentation.
To retrieve the message we construct a URL based on the format described in the documentation.
Make a GET request with the new URL while remembering to pass in the auth
variable we assigned earlier.
Whew 😪 we did it. It only took 7 trips back and forth from the documentation but we finally did it. Now lets take a look at what its like to implement the same flow with Twilio's SDK.
With an SDK
Take a final look at what it looks like to implement this flow without an SDK because you'll never see it again.
Replace the requests import with Twilio's Python SDK
Remove the URL and request body variables as the SDK handles this for us.
Insantiate Twilio's client with credentials instead of creating a raw tuple for our credentials. If we made a typo or forgot to pass our credentials the SDK will let us know ahead of time.
Call client.messages.create and pass in the from_, to, and body
parameters. If we make a typo here the SDK will let us know ahead of time.
Retrieve the sid value from the response without calling .json().
Replace our second request with a simple method call.
By using the SDK we reduced the lines of code by 24% and removed 31% of the variables 🎉.
Take a final look at what it looks like to implement this flow without an SDK because you'll never see it again.
Replace the requests import with Twilio's Python SDK
Remove the URL and request body variables as the SDK handles this for us.
Insantiate Twilio's client with credentials instead of creating a raw tuple for our credentials. If we made a typo or forgot to pass our credentials the SDK will let us know ahead of time.
Call client.messages.create and pass in the from_, to, and body
parameters. If we make a typo here the SDK will let us know ahead of time.
Retrieve the sid value from the response without calling .json().
Replace our second request with a simple method call.
By using the SDK we reduced the lines of code by 24% and removed 31% of the variables 🎉.
SDK vs. no SDK
Lets breakdown through the significant differences that made the SDK code better.
Setup
We do not need to manually construct the URLs to make an HTTP request.
Authentication
Credentials were stored once and stored as part of the SDK. Notice that we did not need to pass in an auth variable again.
Complexity
Making HTTP requests were converted to ergonomic method calls so we deleted a
variable, removed any mention of POST and GET
requests, and removed explicit
JSON deserialization. The SDK also
would have easily caught incorrect argument names when calling create() and
fetch().
Conclusion
SDKs are effective in reducing the pain a developer feels when integrating a REST API. SDKs throw out manual steps from setup/authentication, reduce the cognitive load for the end developer, and reduce the lines of code. Furthermore, SDKs catch compilation or runtime errors earlier in the development process.