Contributing to friendly_shipping, a Ruby library for shipping carrier APIs
If you’ve ever integrated an e-commerce site with a shipping carrier, you know every carrier API is different. Each has its own authentication, its own request formats, and its own ways of reporting errors. friendly_shipping is an open source Ruby gem that puts a single, consistent interface in front of them, and we’ve started contributing to it.
Where it came from
friendly_shipping grew out of real work for one of our longtime e-commerce clients, whose platform needs live rate quotes, address validation, and shipping labels on every order. For years, the go-to library for this in Ruby was Shopify’s active_shipping gem, but it was falling behind as carriers updated their APIs. friendly_shipping was built to replace it, with a fresh design and support for newer services like ShipEngine.
Martin Meyerhoff started the project in late 2018 while working with the same client, and released the first version in May 2019. It has always been a team effort, shaped by the developers working on the client’s platform, and we’re glad to be part of that team.
Our first contributions add UPS address classification, which tells you whether an address is commercial or residential, so you can quote the right rates. We’ve also been improving address validation requests and expanding the gem’s test coverage.
How it works
friendly_shipping currently supports three services:
- UPS: rate estimates, address validation, and address classification
- USPS: rate estimates and address validation
- ShipEngine: carrier listings, rate estimates, shipping labels, and voiding labels
Each one is a service object. Create it with your credentials, then call methods like #rate_estimates, #address_validation, or #labels:
service = FriendlyShipping::Services::ShipEngine.new(
token: ENV['SHIPENGINE_TOKEN'],
test: true
)
service.rate_estimates(shipment, carriers: [carrier])
Shipments, packages, and addresses are modeled with the companion physical gem, so the same shipment works with any carrier. Every call returns a Success or Failure result from dry-monads, carrying the parsed data along with the raw request and response, which makes carrier errors much easier to handle and debug.
Get involved
Install the gem:
gem install friendly_shipping
The project is open source on GitHub under the MIT license. If you run into a bug or need support for another carrier feature, open an issue or send a pull request. Contributions are welcome.
Update: We still contribute to friendly_shipping today, and Matt is now one of its gem authors alongside Martin. Since this post was written, the gem has grown to cover LTL freight carriers like TForce Freight and R+L Carriers, including bills of lading and freight pickups, and has passed 45 releases. See the README on GitHub for current carriers and usage.