Rails Ascent Logo Rails Ascent

Understanding and Using an API: From Introduction to the MAPBOX Example

You've probably already heard of APIs without really understanding what lies behind this mysterious acronym. Yet, these interfaces are everywhere in modern development — they are the invisible cement that makes your applications talk to each other. If you're coming out of Le Wagon or you're just starting in development, understanding APIs is essential to unlock an entire universe of ready-to-use features.


In this article, we're going to demystify this concept together. No heavy jargon, just the essentials so you understand why APIs are essential and how to use them concretely. We'll finish with a practical example: integrating MAPBOX into a Rails application to add interactive maps without reinventing the wheel. Spoiler: without an API, you'd spend weeks building what we can do in a few hours.

Introduction to APIs: What is an API and why are they essential?

An API (Application Programming Interface, or Interface de Programmation d'Applications in French) is simply a contract between two applications. Imagine you're in a restaurant: you are the customer (your application), the cook is an external service (like Google Maps or Twitter), and the waiter is the API. You can't go into the kitchen to prepare your dish, but you can place an order via the server that passes your request and returns the result.

Concretely, an API lets your application request data or services from another application without needing to know how it works internally. You send a request, and you receive a response — usually in JSON or XML.


Why are they essential?

  1. Massive time savings: Rather than coding a payment system yourself, you use the Stripe API.
  2. Access to complex functionalities: Displaying an interactive map? MAPBOX has you covered.
  3. Interoperability: Your applications can talk to other services, databases, third‑party tools.
  4. Automatic updates: If the service improves its features, you benefit without touching your code.


In the world of web development, and especially with Ruby on Rails, APIs are ubiquitous. Whether authenticating users, sending emails, handling payments, or displaying geographic data, you'll spend your time consuming or building APIs.

Understanding the structure and existing API types

Not all APIs look the same. Depending on needs and technologies, you'll encounter several architectures:


1. REST API (Representational State Transfer)

This is the most widespread type of API today. A REST API uses the classic HTTP methods:

  1. GET: retrieve data
  2. POST: create a resource
  3. PUT/PATCH: modify a resource
  4. DELETE: delete a resource


REST APIs are simple, lightweight, and easy to understand. They operate with explicit URLs (for example: https://api.example.com/users/123) and typically return JSON. It’s the standard for most modern web services.


2. SOAP API (Simple Object Access Protocol)

Older and heavier, SOAP APIs use XML and a strict protocol. They’re still used in certain sectors (finance, healthcare) for robustness and security, but they’re much less developer-friendly.


3. GraphQL

Developed by Facebook, GraphQL is a modern alternative to REST. Instead of juggling requests to different endpoints, you ask for exactly the data you need in a single request. It’s powerful, but a bit more complex to set up.


Which type to choose?

To start, focus on REST: it’s the most used and best documented. Most services (MAPBOX, Stripe, Twitter, etc.) offer REST APIs.

Integrating APIs with Ruby on Rails: Basic Principles

Rails is perfectly equipped to work with APIs, whether consuming or creating them. Here are the basics to know:


Consuming an external API in Rails

To call an external API, you’ll typically use gems such as :

  1. HTTParty: simple and effective for making HTTP requests
  2. Faraday: more flexible, with middleware support
  3. Rest-Client: minimalist and straightforward


Basic example with HTTParty :

require 'httparty'
response = HTTParty.get('https://api.example.com/data')
data = JSON.parse(response.body)


Best practices:

  1. Store your API keys in Rails credentials (never hard-coded in the code!)
  2. Handle errors: an API can be temporarily unavailable
  3. Use services or POROs (Plain Old Ruby Objects) to encapsulate API call logic
  4. Cache responses if data changes little (with Redis, for example)

Example of a Rails service to call an API :

class WeatherService
include HTTParty
base_uri 'https://api.weather.com'
def initialize(api_key)
@api_key = api_key
end
def fetch_forecast(city)
response = self.class.get('/forecast', query: { city: city, key: @api_key })
JSON.parse(response.body) if response.success?
end
end


Create your own API with Rails

Rails also lets you turn your application into an API. With rails new mon_app --api, you create an app optimized for serving JSON :

class Api::V1::UsersController < ApplicationController
def index
users = User.all
render json: users
end
def show
user = User.find(params[:id])
render json: user
end
end


Rails handles routing, JSON serialization, and you can easily add authentication with JWT tokens.

Practical Case: Using the MAPBOX API for a Geolocated Project

Now that we’ve laid the groundwork, let’s dive into practice with a concrete example: integrating MAPBOX into a Rails application. MAPBOX is a platform that provides interactive maps, geocoding, and navigation services. It’s the powerful and customizable alternative to Google Maps.


Why use the MAPBOX API?

Imagine you want to display an interactive map on your site with custom markers, zoom, and route calculations. Without an API, you would have to :

  1. Download and host map data (several gigabytes)
  2. Develop a map rendering engine
  3. Implement zooming, panning, and interactions
  4. Manage complex geometric calculations
  5. Keep all that up to date


Estimated time: several weeks, or even months.

With MAPBOX? A few hours at most. You plug into their API, and you gain access to their ecosystem of ready-to-use features. It’s exactly the kind of situation where an API changes the game.

Defining and obtaining the MAPBOX API key

Before coding anything, you need to obtain an API key (also called an access token at MAPBOX). This key lets MAPBOX identify your requests and manage your usage quotas.


Steps to obtain your MAPBOX key:

  1. Create a free account on mapbox.com
  2. Access your Dashboard
  3. Retrieve your Default Public Token or create a new one
  4. Set permissions: for basic web usage, the public token suffices


Important: MAPBOX offers a generous free plan (50,000 map loads per month). Perfect for getting started and testing.


Securing your key in Rails

Never paste your key directly in the code! Use Rails credentials:

RAILS_ENV=development bin/rails credentials:edit
Add your key:
mapbox:
access_token: your_token_here

Then in your code, access it with:

Rails.application.credentials.dig(:mapbox, :access_token)

You can also use an environment variable with the dotenv-rails gem:

# .env
MAPBOX_ACCESS_TOKEN=your_token_here
# In your code
ENV['MAPBOX_ACCESS_TOKEN']

MAPBOX Integration in a Rails Application: Getting Started

Now that we have our key, let's code! We'll display an interactive map with a marker.


1. Install the MAPBOX GL JS SDK

In your layout or view, add MAPBOX CDN links:

If you’re using Webpacker or Importmap, you can also install the npm package.


2. Create a view with a map

In your controller, create an action :

class MapController < ApplicationController
def index
@mapbox_token = Rails.application.credentials.dig(:mapbox, :access_token)
end
end

In the corresponding view :

mapboxgl.accessToken = '';
const map = new mapboxgl.Map({
container: 'map',
style: 'mapbox://styles/mapbox/streets-v12',
center: [2.3522, 48.8566], // Longitude, Latitude of Paris
zoom: 12
});
// Add a marker
const marker = new mapboxgl.Marker()
.setLngLat([2.3522, 48.8566])
.setPopup(new mapboxgl.Popup().setHTML('Bonjour Paris !'))
.addTo(map);


And there you go! You now have a functional interactive map. You can zoom, pan, and click the marker to see a popup.


4. Going further: geocoding and dynamic markers

MAPBOX also offers a geocoding API to transform addresses into coordinates (and vice versa). For example, to search an address :

class GeocodingService
include HTTParty
base_uri 'https://api.mapbox.com'
def initialize
@token = Rails.application.credentials.dig(:mapbox, :access_token)
end
def search(query)
response = self.class.get(
"/geocoding/v5/mapbox.places/#{URI.encode_www_form_component(query)}.json",
query: { access_token: @token }
)
JSON.parse(response.body)
end
end
# Usage
service = GeocodingService.new
results = service.search('Tour Eiffel, Paris')
coordinates = results['features'].first['center'] # [lng, lat]

You can then use these coordinates to place dynamic markers on your front-end map.


4. Best practices for integration

  1. Limit API calls: cache geocoding results in the database
  2. Handle errors: ensure the API responds correctly
  3. Optimize loading: load the map only when necessary (lazy loading)
  4. Customize: MAPBOX lets you create fully custom map styles via Mapbox Studio

Conclusion: Summary and Recommendations

You’ve understood: APIs are phenomenal productivity accelerators. Instead of reinventing the wheel, you leverage proven services that work out of the box. The MAPBOX example perfectly illustrates this philosophy: in just a few lines of code, you get interactive maps that would have required weeks of development from scratch.


For a junior developer fresh out of Le Wagon, mastering APIs is an unnegotiable skill. Whether you’re building an MVP, working on personal projects, or joining a team, you’ll constantly face third-party integrations.

Summary of Key API Features

Keep these essential points about APIs:

  1. Interoperability: APIs allow your applications to talk to other services, creating a connected ecosystem
  2. Modularity: You delegate certain features to specialists (payments, email, mapping) and focus on your core business
  3. Automation: Repetitive tasks (sending emails, complex calculations) are handled by dedicated services
  4. Scalability: When the provider improves its API, you benefit from the new features without a rewrite


REST APIs dominate the market for their simplicity and universality. Understanding how to make HTTP requests (GET, POST, PUT, DELETE) and manipulate JSON is foundational.

Advantages and Challenges of Using MAPBOX

Advantages of MAPBOX:

  1. Massive time savings: interactive maps up and running in under an hour
  2. Advanced features: geocoding, navigation, isochrones, 3D data
  3. Customization: fully customizable map styles
  4. Performance: optimized infrastructure and global CDN
  5. Generous free plan: ideal for startup projects


Potential challenges:

  1. External dependency: if MAPBOX goes down, your map stops working (rare but possible)
  2. Costs beyond the free plan: if your app takes off, costs can rise
  3. Learning curve: the API is rich and takes time to master fully
  4. Quotas and limitations: respect the usage limits of the chosen plan


Overall, the advantages greatly outweigh the drawbacks, especially for launch or experimentation projects.

Recommendations for API Integration in your Projects

To finish, here are some practical recommendations for working effectively with APIs :


1. Read the documentation carefully

It's obvious but crucial. Each API has its own specifics. Take the time to understand endpoints, parameters, response formats, and error codes.


2. Test in a development environment

Most services offer a sandbox or test keys. Use them to experiment risk-free.


3. Secure your API keys

Never hard-code keys in the code! Use Rails credentials or environment variables. And never in a public GitHub repository.


4. Handle errors gracefully

An API can be slow, unavailable, or return errors. Plan for fallbacks, clear error messages and retry mechanisms if needed.


5. Cache responses

If data changes rarely (geocoding, weather information), cache them in the database or with Redis to save calls and improve performance.


6. Monitor your usage

Regularly check your dashboard to verify your usage. You’ll avoid billing surprises or service outages.


7. Test your integrations

Write tests (with RSpec, Minitest) that simulate API responses (with gems like WebMock or VCR) to ensure your code's robustness.


8. Stay up to date

APIs evolve: new versions, endpoint deprecations. Subscribe to the newsletters of services you use.


By applying these principles, you’ll turn APIs from mysterious tools into valuable allies of your development workflow. You’ll gain speed, reliability, and confidence.

So, ready to explore the API universe? Jump in with MAPBOX, experiment, break stuff, and have fun. That’s how you really learn. Happy coding! 🚀