Shipping a great API isn’t just about exposing an endpoint in a RESTful manner. Yes, plenty of developer users will be fine making HTTP requests, but for some, that is not enough. Whether community curated or vendor supplied, code libraries are often created to help extend an application programming interface — API — into specific languages. These libraries help onboard third party users and demonstrate that you’re willing to work on their home turf.

In this first article in a series on supporting your API with code libraries, we examine the importance of helper libraries and how they affect your audience. Backed by research into API library language trends across various industries, we determine what languages you should try to support. We’ll also tune into what players like Twilio and Stripe are doing right to glean helpful best practices.

What Are Helper Libraries?

Helper libraries are developer resources that allow a developer to call an API within the language they are most familiar with, whether it be C#, Ruby, Node.js, Scala, Go, Clojure, Objective-C, or many others. Helper libraries, code libraries, wrappers, Ruby gems, Python bindings, Node.js modules, and Software Developer Kits (SDKs) all help in this regard.

Why Not Just Let Them REST?

Usually, the Uniform Resource Locator — URL — is a friend, allowing access to a specific resource and enabling software to leave isolated environments. The existence of URLs have enabled the Internet, along with an incredible array of products to thrive. However, accessing resources from something other than a web browser can be a complete pain. A cURL POST request to the Twilio API asking to send a text message, for example, may look something like:

$ curl -XPOST https://api.twilio.com/2015-11-09/Accounts/AC5ef823a324940582addg5728ec484/SMS/Messages.json \
	-d “Body=Jenny%20please%3F%21%20I%20love%20you%20<3” \
	-d “To=%2B1415924372” \
	-d “From=%2B424572869” \
	-u ‘AC5ef823a324940582addg5728ec484:{AuthToken}’

This type of request is machine readable, but it involves a lot of encoding and rare symbols to print a relatively simple phrase. Enter REST — a way of building web services by following a set of specific constraints between consumers and providers. The specification describes ways to interact with URLs in a handy and comprehensible method.

However, even if an API is RESTful, the Ruby code required for a POST request to initialize a URI is still clunky. Here is a POST request written in Ruby to access the Rackspace API:

uri = URI.parse(‘https://auth.api.rackspacecloud.com”)
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verifiy_mode = OpenSSL::SSL::VERIFY_NONE
request = NET::HTTP::Post.new(‘/v1.1/auth”)
request.add_field(‘Content-Type’,’application/json’)
request.body = {‘credentials’ => {‘username’ => ‘username’, ‘key’ => ‘key’}}
response = http.request(request)

All this is doing is establishing a connection and verifying credentials. However, if something goes wrong with this request, results things can easily become messy. Most people are aware of HTTP 404 error code (Not found), but there are over 80 other total HTTP error codes specified, and each API’s response behavior is different according to how extensive the provider has chosen to be. Dealing with error codes is a pain, so software engineers have often chosen to abstract and wrap in a method, another reason for adopting helper libraries, according to Wawra.

Data Problem

API providers also need to embrace conventions, and consider what data formats are being used. For example, when you have to send dates, what date standard are you using? Perhaps your service uses a different log than base 10. When users are browsing your documentation, they need to understand it in the scope of their own languages.

This is where helper libraries come into play. Just exposing an HTTP resource is fine, but we need to give developers a bit more help. For example, using a Ruby gem for the Twitter API:

client = Twitter::REST::Client.new do |config|
  config.consumer_key        = "YOUR_CONSUMER_KEY"
  config.consumer_secret     = "YOUR_CONSUMER_SECRET"
  config.access_token        = "YOUR_ACCESS_TOKEN"
  config.access_token_secret = "YOUR_ACCESS_SECRET"
end

client.update(“I’m tweeting with @gem!”)

This simple code found on Github initializes the helper object, and uses it to send a tweet “I’m tweeting with @gem” to Twitter — library. It handles everything we don’t want to care about.

Programming Language Trends

So you’re convinced you need to construct helper libraries for your developer consumers — but now comes the moment of truth. How do we decide which languages to support? Do we address 30+ languages?

To narrow things down, let’s take a look at a couple sources. VentureBeat cites the top 10 languages used on GitHub as:

Adam Duvander, using ProgrammableWeb data, has cited the top languages used for API helper libraries as:

1. PHP
2. Python
3. Ruby
4. .NET / C#
5. Java
6. Perl
7. ColdFusion
8. Node.js
9. ActionScript

Discover What Languages Your Consumers are Using

Regardless of industry trend, the most important step is to listen to your developer consumers — they have likely already told you what languages to add. Discovering this is relatively simple — perform monitoring of the HTTP requests to your server. If you are logging those requests (hopefully this is already the case), then you can easily figure out the user agent for those requests to determine what programming language they are using. Should look like this:

curl/7.31.0
PHP_Request/curl-7.15.5
Java/1.6.0_31

Developer users are your customers. Always respect the fact that your users code, meaning they could always do your job and write their own API if need be. Especially in the case of Twilio, their developers are consuming their API as a time saving mechanism, so the developer experience needs to be as easy as possible. Log activity, determine what your consumers are using, and create developer resources accordingly.

Who Should we Model?

Here is some self-collected data on what languages significant API vendors support for libraries/SDKs across various industries. Twilio has a great outreach library program, as does Stripe. It’s important to note that many helper libraries live in the open source and Github realm — meaning that many libraries are maintained by the surrounding community, perhaps not even touched by the provider themselves.

HTTP is Language Agnostic

With HTTP you can browse the web, make a REST request, hack Snapchat, or make SOAP requests. But helper libraries need to be Language Idiomatic. A Python developer doesn’t care if your libraries behave the same way — they must behave in a way that makes sense for that specific language.

Python example using Twilio’s REST client:

client = TwilioRestClient(“accountSid”, “authToken”)

message = client.messages.create(to=”+12316851234”,
					from_=”_15555555555”,
					body=”Hello there!”)

On the other hand, C# needs to look and behave like C#:

var twilio = new TwilioRestClient(“accountSid”, “authToken”);

var msg = twilio.SendMessage(“+15554446666”,  
                “+15557778888”,  
                “that was easy!”);  

5 Tips for Helper Library Design

• Keep Vocabulary consistent with documentation: Though client libraries need to be catered to the doctrine of the specific language in mind, they still must be consistent with your REST API documentation and parameter vocabulary. These terms should be coherent across all resources that integrate with your platform. Being idiomatic with languages is important, but terms and features need to be consistent.
• Surface Area: How much of your API should your helper library cover? The answer is all. Wawra recommends to marry the API with the web representation. This means that all functions your website can do, your API should handle as well, and in turn your helper library as well. If you are using an API-first building strategy, this becomes a lot more intuitive.
• Simultaneous platform-wide publishing and updates: There is no point in versioning your API or adding new features if your helper libraries are not in sync with updates. The rule of thumb is, for your officially maintained libraries, release changes to API functionality across documentation and all libraries simultaneously.
• TEST: Treat your helper library as a product, and test just as vigorously as you would your API.
• Open Source: It’s not a strategy for every company, but API developers love Github, and providers can benefit from the community aspect of open-sourcing their library. Creating a community around your APIs and libraries encourages improvement to the code.

Last Line of API Code: Your API is Never Really Finished

At the end of the day, the helper library that you ship will live on the user’s app. Since it is in the user’s app — you have limited control. However, developers are always creating new apps, meaning that your API is never truly finished. Having an agile mindset with constant iteration is crucial. Stay tuned for future posts, in which we’ll explore simultaneous platform-wide versioning, how to automate SDK generation using tools like APImatic and RESTUnited, and dive deeper into deciding which is better — open sourcing your helper library or maintaining it internally?