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 a 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:
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:
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!
Understanding the 12-Factor App Methodology
The Axioms of Software Development - Part 10
Understanding User Flows in UX (User Experience) Design
reinteractive is Australia’s largest dedicated Ruby on Rails development company. We don’t cut corners and we know what we are doing.
We are an organisation made up of amazing individuals and we take pride in our team. We are 100% remote work enabling us to choose the best talent no matter which part of the country they live in. reinteractive is dedicated to making it a great place for any developer to work.
Webinars are our online portal for tips, tricks and lessons learned in everything we do. Make the most of this free resource to help you become a better developer.
The Ruby on Rails Installfest includes a full setup of your development environment and step-by-step instructions on how to build your first app hosted on Heroku. Over 1,800 attendees to date and counting.
The Ruby on Rails Development Hub is a monthly event where you will get the chance to spend time with our team and others in the community to improve and hone your Ruby on Rails skills.