Reduce API Consumption Time with SDKs

Developer experience (DevEx) is no longer an unknown term for people in the tech industry. The best way to define DevEx is user experience but for building with the system, not just using it. 

Creating an API is fundamental. Everybody’s doing it. What sets an API apart in a crowded API market is how easy it is to integrate into a developer’s application stack. In this blog, I will be outlining ways to reduce API consumption time.

API Consumption Journey 

There are three distinct phases that an API consumer goes through when wanting to use an API.

API Consumption Approaches

There are two types of providers out there.

1. Those who provide code to show how their API works

2. And those who offer SDKs instead

The difference between these two methods is their approach toward API integration. While code samples make it easier by exposing usage of the API, they sometimes fail to achieve quick API integration.

Let’s look at this API code sample for instance.

At a glance, I can spot the following red flags:

• OkHttpClient is initialized for every call

• Rest information is nested 

• API key is embedded inside the call

• JSON data is all over the place 

• And the list goes on

While this code explains the usage of the endpoint, there’s still a lot of plumbing that needs to be done to make it production-ready. After cycles of refactoring, you will end up with proper libraries that should have been provided to you in the first place. Had your API onboarding experience started with these libraries, there’d be no need for any manual effort. 

I have written another article on taking SDKs beyond API specification wrappers where I discuss the setbacks of client SDKs and how to overcome them. 

SDKs Deliver a Better Developer Experience

SDKs are the key to a world-class developer experience. Many of the API giants push SDKs because they are vital for quick API onboarding. 

One of these API giants, Stripe, endorses the use of SDKs. You will notice other portals adopting the same pattern as well. Instead of showing how their API works, they provide a way to use the API directly in an application, regardless of any language constraints. 

This is just one example of how vital SDKs are in improving developer experience. But not all SDKs deliver this promise. What does? Quality SDKs. 

What Makes Quality SDKs?

Good quality SDKs are:

• Accessible - have code that is easier to understand

• Approachable - have code that is ready for production

• Maintainable - have code that keeps working overtime 

• Robust - have code that works in all cases

• Reliable - have code that works when nothing works 

Let’s look at these qualities in detail.

Accessible

How do SDKs make code easier to understand?

As we saw earlier, a lot of unnecessary information is attached to the code sample. For example, details about whether this endpoint is a POST request or the keys go in the header, these are implementation details of an API that do not help make API onboarding faster.

A client library hides this unwanted information and focuses only on the steps needed to integrate the API. Once you have isolated the API details, your user can easily focus on the implementation, which enhances the developer experience.

Approachable 

SDKs need to ensure that users can use them as quickly as possible. There are a few ways to achieve approachability in SDKs. 

• SDKs that are hosted on package publishing platforms are just one command away from production 

• SDKs need to be easy to initialize. I’m a happy consumer if a simple access token is all it takes to make API calls

• SDKs that have copy-ready code samples. Nobody likes using code samples that look like cooked spaghetti. 

A neat little trick is to drop a complete user application that combines the above-mentioned SDK traits somewhere so users can play around with it. This will ensure maximum client attention.

Maintainable 

Creating SDKs that are maintainable is a challenge, even for us at APIMatic. To achieve maintainability, we create SDKs that:

• Provide types for all possible schemas that an API exposes

• Change according to a new language release or version update 

The reason why maintainability in SDKs is important is simple. Let’s look at this chart that shows versions of different languages released in only 4 years' time. 

This is just one example of how major language churn or any other problem that arises with an external dependency is. SDKs that remain up-to-date and prevent breaking changes regardless of these frequent changes are good SDKs. 

Robust 

Robustness in SDKs means having code that works in all cases. You can ensure this by writing compile-time and runtime checks using models, especially for untyped languages. 

Most popular languages like C# and Java cover a variety of checks themselves, but untyped languages do not have this support. So, it is the API provider’s responsibility to ensure robustness of the code. This helps users who are writing requests to see if they are assigning the right type for the data. 

Having confidence in the request, plus the time it saves the users ultimately results in a better user experience. 

Reliable 

Since client code is usually written in a network system, libraries that cater to the effects of a distributed system change the game. Reliable SDKs have timeouts, retries, API throttling, and circuit breaker in their design. So, even if the network goes down or the server is overloaded, the code recovers from these unforeseen circumstances. By catering to such failure scenarios, SDKs promise client satisfaction. 

Quality SDKs are Closer than You Think

This seems too good to be true; no SDK can have it all. But at APIMatic, we generate SDKs that are approachable, accessible, maintainable, robust, and reliable for speedy API integration. Once you commit to these 5 salient qualities of a quality SDK, you will be able to easily create SDKs that boost API consumption. 

APIMatic’s Chief Product Architect dived deeper into this concept at Apidays New York 2022. Watch what he had to say: