As developers one of the most common tasks we end up doing with our apps is integrating a 3rd-party API into our application. This might be to integrate a payment API using Stripe, Braintree or Pin or to include social media in your backend with the Twitter or Instagram gems or maybe you need to integrate a “legacy” SOAP API into your beautiful clean Rails application.
Here are 3 rules I like to follow when integrating APIs into my Rails applications:
1. Always “wrap” the API in Your Own Class
The Twitter gem is pretty decent, but it’s a general purpose solution to accessing the Twitter API. Your app is likely connecting to the API for a specific reason so creating a wrapper which gives you and your application easy access to the API is a good idea. Also if you do this it’s easier to switch gems or upgrade gem versions in the future since all the changes to your app will be localised in a single class or module.
This approach also means you have a single place in your app to write a 3rd-party integration test with, and you can then safely stub out this section of your app in the rest of your test suite.
To implement this I like to create a class inside app/lib (you might need to create the lib folder). So I might create a simple app/lib/twitter.rb class for my app to use, or maybe I’d create something more fitting to my problem domain. In a fictional app where I search for and display tweets about cats I might call the file app/lib/twitter_cats.rb. The class inside this file would match the name and would handle everything to do with the Twitter gem itself.
2. Never Store your API Keys in Git
Even for simple learning projects you should never store your API keys in Git. This is a really big security vulnerability. There are, apparently, bots that go through the GitHub commit feed and strip out interesting API keys from projects that are accidentally committed.
So, instead of commiting your config/initializers/instagram.rb file with all that secret API information create a file that looks like this instead:
Ruby
Instagram.configure do |config|
config.client_id = ENV["INSTAGRAM_CLIENT_ID"]
config.client_secret = ENV["INSTAGRAM_CLIENT_SECRET"]
end
Then install a gem like dotenv and configure a .env project file (and add it to your .gitignore) or use direnv and create an .envrc file (and add it to your .gitignore). Personally I use direnv because it’s more flexible. Inside either of these project-specific env files you add whatever environment variables you need to add:
bash
export INSTAGRAM_CLIENT_SECRET=<YOUR SECRET HERE>
export INSTAGRAM_CLIENT_ID=<YOUR ID HERE>
3. Always Store the Full Response
When working with an API it’s very common that you only want to work with a tiny section of the actual response. If you’re building an app where you persist data in your database based off the response from the API persist the entire response along-side the individual attributes you’re extracting out. This lets you extract more information out of the response if you need to later on in the project’s lifetime.
For example, assume you’re importing products from a wholesale API system into your fancy new Rails e-commerce site. Initially you decide that you don’t want to deal with delivery data which the wholesale API system supplies. In a few months some new requirements arrive and you’re required to support those delivery fields in your app.
If you had stored all the response data (for example in a JSON field) you would be able to run a simple data-migration to populate your database. If you didn’t store the full response data, instead, you would need to re-import all your products, a huge time sink that might also affect your analytics.
If you’re allowed to, store the full response. Storage is cheap and your time is precious. Do you have any questions about the content? Any quick tips on integrating 3rd-party APIs into your apps? Let me know what they are!
