16/04/2021
Sviluppare API con Ruby on Rails: la gemma Grape
Nell’ambito dello sviluppo in Ruby On Rails, spesso è necessario estendere le applicazioni Web con le c.d. API per supportare sia chi nel team si sta occupando dello sviluppo mobile sia chi tanto vorrebbe sviluppare una PWA utilizzando gli stessi dati.
A tal fine, ci viene incontro Grape, un framework per creare REST-like API in Ruby, progettato per girare su Rack o per integrarsi con framework come Ruby on Rails e Sinatra attraverso un semplice DSL. Lo strumento offre il supporto integrato per le convenzioni comuni, tra cui i formati multipli, sottodomini, negoziazione dei contenuti, controllo delle versioni.
Sono diversi i motivi per cui scegliere di utilizzare Grape; tra questi:
- Sintassi semplice per definire gli endpoint
- Un metodo semplice di formattare i dati
- Aggiunta di parametri e validazione semplice
- Supporto integrato per il versionamento
- Velocità di chiamata delle API
- Documentare gli endpoint è quasi gratis e immediato
INSTALLAZIONE
Per poter utilizzare effettivamente Grape abbiamo bisogno di installare e configurare alcune gemme aggiuntive.
Modifichiamo pertanto il nostro Gemfile aggiungendo le seguenti righe:
# Gemfile
...
gem 'grape'
gem 'grape-entity'
gem 'grape-swagger'
...
Possiamo adesso quindi installare le gemme appena aggiunte lanciando bundle install.
CONFIGURAZIONE
Passiamo ora alla parte di configurazione. Prima di tutto dobbiamo “far comprendere” alla nostra applicazione dove trovare le API aggiornando application.rb.
# config/application.rb
...
config.paths.add File.join(‘app’, ‘api’), glob: File.join(‘**’, ‘*.rb’)
config.autoload_paths += Dir[Rails.root.join(‘app’, ‘api’, ‘*’)]
...
E aggiornare le routes.rb:
# config/routes.rb
...
mount API::Base => '/api'
...
A questo punto, dobbiamo creare la nostra cartella API in controllers con al suo interno due sottocartelle con nome entities e l’altra v1 che conterranno gli endpoint.
Avremo quindi due percorsi del tipo: /app/controllers/api/entities e /app/controllers/api/v1
Si procede alla creazione delle API con Grape, creando una normalissima applicazione Web; pertanto abbiamo bisogno di un “cuore” da cui partire e nel caso di Grape è il file base.rb che andiamo a posizionare in /app/controllers/api/base.rb e all’interno ci aggiungiamo il seguente codice:
# /app/controllers/api/base.rb
module API
class Base < Grape::API
mount API::V1::Base
add_swagger_documentation
end
end
Abbiamo cosi ottenuto lo scheletro delle nostre API e non ci resta che scrivere i nostri endpoint all’interno delle rispettive cartelle.
LA NOSTRA PRIMA API
Come fatto con base.rb, analogamente creiamo un file per ogni entità per la quale vogliamo realizzare delle API; ad esempio, supponendo di avere il model Article nel nostro progetto, avremo in /entities un file article.rb nel quale verranno inseriti tutti i valori che vogliamo presentare per le chiamate delle API per gli articoli, ad esempio:
# /app/controllers/api/entities/article.rb
module API
module Entities
class Article < Grape::Entity
expose :id
expose :title
expose :description
expose :author
end
end
end
Infine nella cartella /v1 avremo un file articles.rb in cui scriveremo tutte le API necessarie nel seguente modo:
# /app/controllers/api/v1/articles.rb
module API
module V1
class Articles < Grape::API
version ‘v1’
format :json
resource :articles do
desc “Indice articoli”
get do
articles = Article.all
present articles, with: API::Entities::Article
end
end
end
end
end
CONCLUSIONI
Abbiamo visto come, in pochi e semplici passaggi possiamo realizzare delle API funzionanti per rendere la nostra applicazione ancora più ricca e completa di funzionalità.
Ovviamente quello mostrato in esempio è un utilizzo estremamente basilare della gemma Grape che in realtà presenta una quantità notevole di funzioni specifiche ed estremamente utili.
Per ogni ulteriore approfondimento si rimanda alla pagina della gemma.
