Retour

Construire des APIs modernes avec Ruby on Rails : REST, JSON, GraphQL, Turbo & plus encore

Série: API avec Ruby on Rails
Enregistrer
Temps de lecture: 4 min Vues: 96 Niveau: Intermédiaire à Confirmé
3 mois par Franci-lobbie LALANE
Construire des APIs modernes avec Ruby on Rails : REST, JSON, GraphQL, Turbo & plus encore
Tags:
#API #Ruby on Rails

Introduction

Dans le développement web moderne, construire une API robuste et bien pensée est devenu un prérequis pour tout projet sérieux. Ruby on Rails, souvent associé au développement HTML full-stack, offre en réalité une palette complète pour concevoir des APIs puissantes : REST, GraphQL, WebSockets, Turbo…
Rails 7.1 nous fournit une infrastructure élégante et cohérente qui permet de choisir parmi plusieurs architectures API, sans jamais sacrifier la lisibilité ni la productivité. Cet article s’adresse aux développeurs Ruby intermédiaires à avancés souhaitant approfondir leurs compétences dans la conception d’APIs professionnelles.

1. Rails en mode API-first : minimalisme assumé

Depuis Rails 5, le mode --api permet de générer une application allégée :

rails new my_api_app --api

Ce mode supprime les vues, assets, helpers HTML, middleware CSRF, et tout ce qui ne sert pas une API JSON. Résultat : une application plus rapide au démarrage, plus claire dans sa structure, et mieux adaptée aux API-first architectures.
🔍 Le contrôleur hérite de ActionController::API, avec une stack HTTP optimisée.
💡 À noter : vous pouvez toujours réactiver certains composants si nécessaire (views, middleware supplémentaires, etc.).
📦 Exemple d’ajout du middleware Rack::Cors pour autoriser les requêtes cross-origin :

# config/initializers/cors.rb
Rails.application.config.middleware.insert_before 0, Rack::Cors do
  allow do
    origins '*'
    resource '*', headers: :any, methods: [:get, :post, :patch, :put, :delete, :options]
  end
end


2. Construire une API REST propre, maintenable et évolutive

REST est la pierre angulaire des APIs bien conçues. Rails suit les conventions REST de manière très intuitive.

Structure des routes :

namespace :api do
  namespace :v1 do
    resources :articles
  end
end

Dans vos contrôleurs :

class Api::V1::ArticlesController < ApplicationController
  def index
    articles = Article.all
    render json: ArticleSerializer.new(articles).serializable_hash
  end
end

💎 Pour une architecture plus riche :
  • Ajoutez une couche de services (e.g. ArticleFetcherService) pour isoler la logique métier.
  • Utilisez des policies (Pundit) pour sécuriser l'accès aux données.
🔧 Serialisation JSON :
  • Blueprinter (rapide, lisible, flexible)
  • ActiveModel::Serializers (plus verbeux, mais structurant)

Pagination :

include Pagy::Backend
@pagy, @articles = pagy(Article.all)

Utilisez des scopes de tri et de recherche avec ransack :

Article.ransack(title_cont: "Rails").result

➡️ Pensez aussi au versionnement de votre API, à la gestion des erreurs centralisée, et à une documentation claire (cf. rswag).


3. GraphQL avec graphql-ruby : précision et expressivité

GraphQL permet aux clients de spécifier exactement les données attendues. C’est une alternative puissante à REST quand les besoins en données sont complexes ou très variables.

Installation :

bundle add graphql
rails generate graphql:install

Exemple de type :

class Types::ArticleType < Types::BaseObject
  field :id, ID, null: false
  field :title, String
  field :content, String
end

Requête client :

query {
  articles { id title content }
}

🔥 Points forts :

  • Flexibilité du client
  • Moins de sur-fetching
  • Documentation générée automatiquement (GraphiQL)

⚠️ Attention :

  • Implémentation plus lourde côté backend
  • Caching plus complexe

💡 Astuce : utilisez GraphQL::Dataloader pour éviter les requêtes N+1.


4. WebSockets avec Action Cable : vers une API en temps réel

Action Cable est intégré nativement à Rails pour gérer les WebSockets. Pratique pour les notifications, chats, collaborations en direct.

Exemple de canal :

class NotificationsChannel < ApplicationCable::Channel
  def subscribed
    stream_from "notifications_#{current_user.id}"
  end
end

Diffusion :

Turbo::StreamsChannel.broadcast_append_to(
  "notifications_#{user.id}",
  target: "notifications",
  partial: "notifications/item",
  locals: { notification: Notification.last }
)

Combinez cela avec Turbo Streams pour une interface ultra réactive, sans rechargement de page.


5. Turbo & Hotwire : l’API HTML intelligente

Turbo Streams transforme votre HTML serveur en API efficace. Chaque interaction peut renvoyer un fragment HTML prêt à s’insérer dynamiquement dans le DOM.

Exemple : ajout de commentaire en live :

<%= turbo_frame_tag "comment_form" do %>
  <%= form_with model: @comment %>
<% end %>

<%= turbo_stream.append "comments" do %>
  <%= render @comment %>
<% end %>

✅ Bénéfices :

  • UX fluide sans JS custom
  • Requête standard HTTP
  • Moins de logique côté frontend

🔗 Combinez avec Stimulus pour des comportements enrichis.


6. Authentification et sécurité : protéger votre API

Plusieurs stratégies existent pour authentifier les requêtes API :
🔐 Auth Token simple : Devise Token Auth 🔐 JWT : warden-jwt_auth, devise-jwt 🔐 OAuth2 : Doorkeeper (authentification tierce, scopes, expiration…)

Sécurisation des endpoints :

class Api::V1::BaseController < ApplicationController
  before_action :authenticate_user!
end

🛡 Pensez aussi à :

  • rack-attack pour limiter les abus
  • secure_headers pour durcir la sécurité HTTP
  • auditing/logging des accès sensibles


7. Tester son API : pilier de la robustesse

Les tests garantissent la stabilité et la non-régression de votre API.
RSpec avec des request specs :

describe "GET /api/v1/articles" do
  it "returns articles" do
    get "/api/v1/articles"
    expect(response).to have_http_status(:ok)
  end
end

Complétez avec :

  • FactoryBot pour la fabrication de données
  • JSON helpers pour simplifier les assertions
  • rswag pour documenter l’API en Swagger
  • VCR/WebMock pour mocker les appels externes

➡️ Objectif : CI rapide, couverture complète, spécifications vivantes.


Conclusion : Rails, un framework API à tout faire

Rails ne se limite plus au rendu HTML. Il devient un vrai socle pour bâtir des architectures API modernes, scalables et maintenables. REST, GraphQL, WebSockets, HTML dynamique – tout est possible sans plugin exotique, sans surcharge technique.

👉 En API-first ou full-stack enrichi, Rails reste l’un des frameworks les plus productifs et polyvalents.

N’attendez plus pour repenser vos APIs avec Rails 7.1.


Happy coding !

Laissez un commentaire

Se connecterpour laisser un commentaire.

adam-lamouri
@adam-lamouri 3 mois

Super résumé de la puissance d'une api Rails, par contre moi j'ai beaucoup de souci a implémenter l'authentication via Devise en API... la doc est super mal faite

1